diff --git a/README-DEVELOPER.md b/README-DEVELOPER.md deleted file mode 100644 index 95e9f1b..0000000 --- a/README-DEVELOPER.md +++ /dev/null @@ -1,230 +0,0 @@ -[![npm (scoped)](https://img.shields.io/npm/v/xpm.svg)](https://www.npmjs.com/package/xpm/) -[![license](https://img.shields.io/github/license/xpack/xpm-js.svg)](https://github.com/xpack/xpm-js/blob/master/LICENSE) -[![Standard](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com/) -[![CI on Push](https://github.com/xpack/xpm-js/actions/workflows/node-ci.yml/badge.svg)](https://github.com/xpack/xpm-js/actions/) -[![GitHub issues](https://img.shields.io/github/issues/xpack/xpm-js.svg)](https://github.com/xpack/xpm-js/issues/) -[![GitHub pulls](https://img.shields.io/github/issues-pr/xpack/xpm-js.svg)](https://github.com/xpack/xpm-js/pulls/) - -# Developer info - -This page documents the prerequisites and procedures used during the -development of the `xpm` module. - -This project is currently written in JavaScript, but a rewrite to -TypeScript is planned. - -## Prerequisites - -The prerequisites are: - -- git -- node >= 14.13.1 (for stable modules) -- npm - -## Clone the project repository - -The project is hosted on GitHub: - -- - -To clone the `master` branch, use: - -```sh -mkdir "${HOME}/Work/node-modules" && cd "${HOME}/Work/node-modules" -git clone https://github.com/xpack/xpm-js.git xpm-js.git -``` - -For development, to clone the `develop` branch, use: - -```sh -git clone --branch develop https://github.com/xpack/xpm-js.git xpm-js.git -``` - -## Satisfy dependencies - -```sh -npm install -``` - -To later check for newer dependencies: - -```sh -npm outdated -``` - -Details about dependencies: - -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- - -## Language standard compliance - -The module uses ECMAScript 6 class definitions and modules. - -## Standard style - -As style, the project uses the -[JavaScript Standard Style](https://standardjs.com/), -automatically checked at each commit via CI. - -Generally, to fit two editor windows side by side in a screen, -all files should limit the line length to 80. - -```js -/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */ -``` - -Known and accepted exceptions: - -- none - -To manually fix compliance with the style guide (where possible): - -```console -$ npm run fix - -> xpm@0.16.2 fix -> standard --fix -``` - -## Tests - -The tests use the [`node-tap`](http://www.node-tap.org) framework -(_A Test-Anything-Protocol library for Node.js_, written by Isaac Schlueter). - -As for any `npm` package, the standard way to run the project tests is -via `npm test`: - -```sh -cd xpm-js.git -npm install -npm run test -``` - -To run a specific test with more verbose output, use `npm run tap`: - -```sh -npm run tap test/tap/... -``` - -### Coverage tests - -Coverage tests are a good indication on how much of the source files is -exercised by the tests. Ideally all source files should be covered 100%, -for all 4 criteria (statements, branches, functions, lines). - -To run the coverage tests, use `npm run test-coverage`: - -```sh -npm run test-coverage -... -``` - -#### Coverage exceptions - -Use `/* istanbul ignore next */` before the code to be ignored -(). - -Fully excluded files: - -- `lib/utils/cmd-shim.js` - -### Continuous Integration (CI) - -The continuous integration tests are performed via -GitHub Actions. - -The tests are currently performed with node 14, 16, 18. - -To preserve compatibility with Node 10, use the older -version of the documentation: - -- [Node.js 14 documentation](https://nodejs.org/docs/latest-v14.x/api/) - -### Documentation metadata - -The documentation metadata follows the [JSdoc](http://usejsdoc.org) tags. - -To enforce checking at file level, add the following comments right after -the `use strict`: - -```js -'use strict' -/* eslint valid-jsdoc: "error" */ -/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */ -``` - -Note: be sure C style comments are used, C++ styles are not parsed by -[ESLint](http://eslint.org). - -## Dependencies issues - -There were some problems with cacache & pacote. - -- cacache@15.0.3: fails to download binaries. -- pacote@11.1.10: apparently works, but passing the stream to cacache fails. - -The previous known to work versions: - -```js - "cacache": "^12.0.2", - "pacote": "^9.4.1", -``` - -Note: the cacache version should match the one used inside pacote. - -- -- - -TODO: investigate and update. - -## Project templates - -**xpm** is able to create new projects based on templates. - -To be accepted as a template, a project must: - -- be an xPack (have a `package.json` which includes an `xpack` property -- have a property called `main` in `package.json`, pointing to a JavaScript - file that can be consumed by `await import()` (formerly `require()`) -- the main file must export a class called `XpmInitTemplate` -- an instances of this class must have a `run()` method. -- have all dependencies bundled in (via `bundleDependencies`) - -The steps invoked by **xpm** to initialise a project from a template are: - -- call pacote to install the xPack in the global home folder -- identify the `main` property in `package.json` -- import the `XpmInitTemplate` class from the main JavaScript file by - invoking _require()_ -- instantiate the `XpmInitTemplate` class -- execute the `run()` method. - -The full code is in `init.js`, but a simplified version looks like this: - -```js - await pacote.extract(config.template, globalPackagePath, - { cache: cacheFolderPath }) - - const mainTemplatePath = path.join(globalPackagePath, globalJson.main) - - context.CliError = CliError - context.CliExitCodes = CliExitCodes - - const { XpmInitTemplate } = await import(mainTemplatePath) - const xpmInitTemplate = new XpmInitTemplate(context) - const code = await xpmInitTemplate.run() -``` diff --git a/README-long.md b/README-long.md deleted file mode 100644 index a4dcc34..0000000 --- a/README-long.md +++ /dev/null @@ -1,243 +0,0 @@ -[![npm (scoped)](https://img.shields.io/npm/v/xpm.svg)](https://www.npmjs.com/package/xpm/) -[![license](https://img.shields.io/github/license/xpack/xpm-js.svg)](https://github.com/xpack/xpm-js/blob/master/LICENSE) -[![Standard](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com/) - -# xpm - the xPack project manager - -This project implements `xpm` - the **xPack project manager** - -as a Node.js CLI application. - -The main purpose of `xpm` is to **automate common tasks** and **provide -reproducible builds** for language neutral, multi-version projects. - -More specifically: - -- to manage **build configurations** and to run **actions** (sequences of commands) -associated with various build steps -- to manage versioned **dependencies**, like to install both **source code libraries** -and **binary archives**, and to easily update them when new versions are -available - -So far, two main use cases were considered and successfully implemented: - -- to orchestrate complex multi-architecture/multi-platform builds for -embedded projects (like semihosted unit tests for **µOS++**) -- to perform the multi-platform builds for all binary tools part of the -[xPack 3rd Party Development Tools](https://github.com/xpack-dev-tools/) -project. - -The project is open-source and is hosted on GitHub as -[xpack/xpm-js](https://github.com/xpack/xpm-js.git). - -## Maintainer info - -This page is intended as a brief introduction for those who consider -using this tool to manage their projects. - -For developer and maintainer information, see the separate -[`README-DEVELOPER.md`](https://github.com/xpack/xpm-js/blob/master/README-DEVELOPER.md) -and -[`README-MAINTAINER.md`](https://github.com/xpack/xpm-js/blob/master/README-MAINTAINER.md) -pages. - -## Quick links - -If you already know the general facts about `xpm`, you can directly skip to: - -- project [web site](https://xpack.github.io/xpm/) -- [releases](https://xpack.github.io/xpm/releases/) -- [GitHub](https://github.com/xpack/xpm-js.git) -- [how to install](https://xpack.github.io/xpm/install/) -- [how to get support](https://xpack.github.io/xpm/support/) -- [npmjs/xpm](https://www.npmjs.com/package/xpm/) -- published [versions](https://www.npmjs.com/package/xpm?activeTab=versions) - -## xPacks overview - -**xPacks** are general purpose versioned software packages, -much the same as the highly successful -[npm packages](https://docs.npmjs.com/getting-started/what-is-npm) -in the [Node.js](https://nodejs.org/en/) ecosystem. - -xPacks are usually Git repositories and can be published on -[npmjs.com](https://npmjs.com/) or any npm compatible server. - -For more details, please read the -[xPacks 101](https://xpack.github.io/intro/) page. - -## Prerequisites - -The current version requires Node.js >= 18. - -Since it is highly recommended to **do not** use `sudo` during install, -and instead -**use a version manager** or to customize the **npm** install location, -please read the -[install](https://xpack.github.io/xpm/install/) page for more details. - -## Install - -The basic command is: - -```sh -npm install --global xpm@latest -``` - -Troubleshooting: in case `xpm` was already installed, in certain conditions -the update may not succeed and **xpm** may become unusable; if this happens, -uninstall **xpm** and retry the install. - -For more details, please refer to the -[install](https://xpack.github.io/xpm/install/) page. - -## User info - -To get an initial glimpse on the program, ask it for help: - -```console -% xpm --help - -The xPack project manager command line tool -Usage: xpm [...] [ ...] [...] - -where is one of: - init, install, link, list, run, uninstall - -Common options: - --loglevel Set log level (silent|warn|info|verbose|debug|trace) - -s|--silent Disable all messages (--loglevel silent) - -q|--quiet Mostly quiet, warnings and errors (--loglevel warn) - --informative Informative (--loglevel info) - -v|--verbose Verbose (--loglevel verbose) - -d|--debug Debug messages (--loglevel debug) - -dd|--trace Trace messages (--loglevel trace, -d -d) - --no-update-notifier Skip check for a more recent version - -C Set current folder - -xpm -h|--help Quick help -xpm -h|--help Quick help on command -xpm --version Show version -xpm -i|--interactive Enter interactive mode - -npm xpm@0.19.4 '/Users/ilg/.nvm/versions/node/v16.16.0/lib/node_modules/xpm' -Home page: -Bug reports: -``` - -## Configuration - -Similarly to **npm**, the project configuration is in `package.json`. - -In addition to `name` and `version` which must uniquely identify the project, -there is an `xpack` property that groups several **xpm** -specific properties: - -- `dependencies` -- `devDependencies` -- `properties` -- `actions` -- `buildConfigurations` - -`dependencies` and `devDependencies` are similar to **npm**, but refer to -xPacks. `properties` define values used in substitutions. `actions` are a -more generalised form of the **npm** scripts, which allow arrays of -commands with substitutions. `buildConfigurations` define multiple -configurations, like debug/release. - -## Template substitutions - -To increase reusability, it is possible to use **substitutions** -in the strings defining actions. The syntax is more elaborate than the simple -variable substitution, and is using the -[LiquidJS](https://liquidjs.com/) template engine syntax, -which accepts: - -- **variables**, like `{{ configuration.name }}` -- **filters**, like `{{ configuration.name | downcase }}` -- **tags**, like `{% if os.platform != 'win32' %}xpm run execute --config synthetic-posix-cmake-debug{% endif %}` - -The substitution values come from the following predefined objects: - -- `package`, with the entire `package.json` content -- `properties` with the xPack properties -- `os.platform` with the Node.js platform (possible values are `aix`, - `darwin`, `freebsd`, `linux`, `openbsd`, `sunos`, and `win32`) -- `os.arch` with the Node.js architecture (possible values are `arm`, - `arm64`, `ia32`, `mips`, `mipsel`, `ppc`, `ppc64`, `s390`, `s390x`, - `x32`, and `x64`) - -When the `xpm` command is started with `--config`, -the configuration properties are preferred to the xPack -properties and the following object is also added to `properties`: - -- `configuration` with the full content of the current xPack build - configuration; - the configuration name is available as `configuration.name` - -For the full list of variables available for substitutions, please -read the [documentation](https://xpack.github.io/xpm-liquid-ts/) of -the separate [xpack/xpm-liquid-ts](https://github.com/xpack/xpm-liquid-ts/) -project. - -## Multi-line actions - -In order to accommodate more complex actions, it is possible to define -sequences of commands as arrays of strings, with each line executed as -a separate command. - -If multiple commands are generated via loops, line terminators can be inserted -with `{{ os.EOL }}`), for example: - -```liquid -{% for command in package.xpack.my_commands %}{{ command }}{{ os.EOL }}{% endfor %} -``` - -### The build folder path - -When using build configurations, each build must be performed in a -separate build folder. - -This should be done using the reserved property `buildFolderRelativePath`, -which must define a folder relative to the project root, usually below -a top `build` folder. - -This property can be defined either manually for each configuration, -or globally, as a computed property, available for the entire project. - -The definition can be parametrised with the configuration name, -and possibly converted to a lower case folder name, for example: - -```json - "xpack": { - "properties": { - "buildFolderRelativePath": "{{ 'build' | path_join: configuration.name | to_filename | downcase }}" - } - } -``` - -## Change log - incompatible changes - -According to [semver](https://semver.org) rules: - -> Major version X (X.y.z | X > 0) MUST be incremented if any -backwards incompatible changes are introduced to the public API. - -The incompatible changes, in reverse chronological order, are: - -- v0.19.x: compatible, but based on node 18 -- v0.14.x: separate xPack from npm dependencies (see -[0001](https://xpack.github.io/xpm/policies/0001/) policy) - -## License - -The original content is released under the -[MIT License](https://opensource.org/licenses/MIT), with all rights -reserved to [Liviu Ionescu](https://github.com/ilg-ul/). - -The design is heavily influenced by the `npm` application, -**Copyright (c) npm, Inc. and Contributors**, Licensed on the -terms of **The Artistic License 2.0**. - -## Note - -The **xpm** tool is currently work in progress and should be used with caution. diff --git a/docs/package.json.md b/docs/package.json.md deleted file mode 100644 index 5af6597..0000000 --- a/docs/package.json.md +++ /dev/null @@ -1,68 +0,0 @@ - - -# Additions to package.json - -Generally, for compatibility reasons, there should be no -additions/changes in `package.json`, except the `xpack` object. - -## `xpack` - -Type: object. - -Properties: - -- `folderName` -- `directories` - -## `folderName` - -Type: string - -By default, when xPacks are installed by `xpm`, a folder derived -from the package name is used. If the package is scoped, the scope is -used to prefix the name. For example, an xPack named `@micro-os-plus/startup` -will be installed in `micro-os-plus-startup`. - -The optional `folderName` property can be used to configure a custom -name for the folder where the xPack is installed. - -Example: - -```json -{ - "...": "...", - "xpack": { - "folderName": "my-special-name" - } -} -``` - -## `directories` - -Type: object. - -This definition is similar to the one used by `npm`, but adds different -names and allows for arrays of folders. - -Properties: - -- `xpacks`: the location where `xpm` will install dependent xPacks; the -default is `./xpacks`; -- `src`: the location of folders with source files; the default is `./src`; -- `include`: the location of folders with include files; the default -is `./include`; - -Example: - -```json -{ - "...": "...", - "xpack": { - "directories": { - "xpacks": "./my-packs", - "src": [ "./src", "./libs/src" ], - "include": [ "./include", "./libs/include" ] - } - } -} -``` \ No newline at end of file diff --git a/docs/symlinks.md b/docs/symlinks.md deleted file mode 100644 index 0dfb6d9..0000000 --- a/docs/symlinks.md +++ /dev/null @@ -1,26 +0,0 @@ -# Windows symbolic links - -## Brief - -The short version is that Windows does not support symbolic links. - -## Problem - -NTFS supports only _junctions for directories_ (whatever this can be). - -According to tests on a recent (2004, build 19041): - -- `mklink /J new old` - creates a directory junction, no admin rights; works on different partitions or volumes, but only locally on the same computer -- `mklink /D new old` - creates a symbolic link, but requires admin rights or developer mode; can point to any file or folder either on the local computer or using a SMB path to point at targets over a network - -https://www.2brightsparks.com/resources/articles/NTFS-Hard-Links-Junctions-and-Symbolic-Links.pdf - -Rumors say that since Windows 10 Insiders build 14972, symlinks can be created without admin rights (https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/), but tests on build 19041 did not confirm this. - -## Solution - -The solution is to use wrappers, to call executables from a different folder. - -- shell wrappers for mingw cases -- `.cmd` wrappers for old DOS -- `.ps1` wrappers for new power shell (not yet implemented) diff --git a/website/docs/developer/_common/_prerequisites.mdx b/website/docs/developer/_common/_prerequisites.mdx index 32f090f..337f75f 100644 --- a/website/docs/developer/_common/_prerequisites.mdx +++ b/website/docs/developer/_common/_prerequisites.mdx @@ -7,12 +7,14 @@ import CodeBlock from '@theme/CodeBlock'; ## Prerequisites -The **xPack Project Manager** is a portable Node.js project, and development can be +**xpm** is a portable Node.js module; +development can be performed on macOS, GNU/Linux and even Windows (although some npm scripts -require bash). +must be executed in a Git Bash terminal). The prerequisites are: +- git - node >= {props.nodeVersion || 'N.N.N'} - npm diff --git a/website/docs/developer/index.mdx b/website/docs/developer/index.mdx index 0723009..6b79833 100644 --- a/website/docs/developer/index.mdx +++ b/website/docs/developer/index.mdx @@ -39,6 +39,11 @@ or fix bugs in the **xPack Project Manager** project and provides documentation on how to build and test the package. + +This project is currently written in JavaScript, but a rewrite in +TypeScript is planned. + + @@ -81,23 +86,30 @@ this, start it in `watch` mode. ```sh npm run compile-watch ``` +## Language standard compliance + +The module uses ECMAScript 6 class definitions and modules. ## Standard style -As style, the project uses `ts-standard`, the TypeScript variant of -[Standard Style](https://standardjs.com/#typescript), + +As style, the project uses the +[JavaScript Standard Style](https://standardjs.com/), automatically checked at each commit via CI. +For spacial cases, it is possible to configure/disable some rules. + ```js -// eslint-disable-next-line @typescript-eslint/no-xxx-yyy +/* eslint-disable-next-line no-xxx-yyy */ ``` The known rules are documented in the -[typescript-eslint](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin/docs/rules) +[eslint](https://eslint.org/docs/latest/rules/) project. + Generally, to fit two editor windows side by side in a screen, all files should limit the line length to 80. @@ -115,34 +127,34 @@ To manually fix compliance with the style guide (where possible): `% npm run fix > xpm@${customField('version')} fix -> ts-standard --fix src && standard --fix test +> standard --fix test ... `} ## Documentation metadata -The documentation metadata uses the -[TypeDoc](https://typedoc.org/guides/doccomments/) tags, without -explicit types, since they are provided by TypeScript. -:::note +The documentation metadata follows the [JSdoc](http://usejsdoc.org) tags. -Microsoft is currently developing a new project ([TSDoc](https://tsdoc.org)) -which tries to standardise TypeScript documentation metadata. +To enforce checking at file level, add the following comments right after +the `use strict`: -This standard is generaly compatible with TypeDoc; at the time of -this writing, among the visible differences is the lack -of the `@category` or `@group` tags. +```js +'use strict' +/* eslint valid-jsdoc: "error" */ +/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */ +``` + +Note: be sure C style comments are used, C++ styles are not parsed by +[ESLint](http://eslint.org). -::: ## Tests The tests use the [`node-tap`](http://www.node-tap.org) framework (_A Test-Anything-Protocol library for Node.js_, written by Isaac Schlueter). -Tests can be written in TypeScript, assuming `ts-node` is also installed -(https://node-tap.org/docs/using-with/#using-tap-with-typescript) +Tests can be written in TypeScript, assuming `ts-node` is also installed. As for any `npm` package, the standard way to run the project tests is via `npm run test`: @@ -161,14 +173,8 @@ npm run test The module is CI tested on every push via [GitHub Actions](https://github.com/xpack/xpm-js/actions), on Ubuntu, -Windows and macOS, using node 18 and 20. - -## Tricks & tips +Windows and macOS, using node 18, 20 and 22. -To trace TypeScript module resolution: -```json - "compile": "tsc --traceResolution -p ./", -``` diff --git a/website/docs/developer/windows-symbolic-links/index.mdx b/website/docs/developer/windows-symbolic-links/index.mdx new file mode 100644 index 0000000..152dd68 --- /dev/null +++ b/website/docs/developer/windows-symbolic-links/index.mdx @@ -0,0 +1,89 @@ +--- + +title: Windows symbolic links +description: Why symbolic links to files cannot be used on Windows +keywords: + - xpack + - xpm + - windows + - symbolic + - links + +date: 2022-04-19 16:23:00 +0300 + +--- + +# Windows symbolic links + +## Brief + +The short version is **Windows does not support symbolic links to files**. + +## Problem + +By design, **npm** required a method to differentiate between multiple +applications installed in distinct folders. The traditional method is +to add multiple paths to `PATH`. However, **npm** preferred a different +method: creating symbolic links to individual applications in a `.bin` +folder and adding this folder to the top of the PATH. + +This works very well on Unix systems, but is not applicable on Windows, +as there are no symbolic links to files. + +NTFS supports only _junctions for directories_ (whatever this can be). + +According to tests on a Windows system (2004, build 19041): + +- `mklink /J new old` - creates a directory junction, no admin rights; works on different partitions or volumes, but only locally on the same computer +- `mklink /D new old` - creates a symbolic link, but requires admin rights or developer mode; can point to any file or folder either on the local computer or using a SMB path to targets over a network + +Reference: + +- https://www.2brightsparks.com/resources/articles/NTFS-Hard-Links-Junctions-and-Symbolic-Links.pdf + +Rumours say that since Windows 10 Insiders build 14972, symlinks can be created without admin rights (https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/), but tests on build 19041 did not confirm this; therefore this method was considered unreliable. + +## Solution + +The solution is to use wrappers/shims, to call executables from a different folder. + +- shell wrappers for mingw cases +- `.cmd` wrappers for old DOS +- `.ps1` wrappers for new Power Shell + +For now the binaries are invoked directly from the actual install location, +not from the junction created in the local project. + +## Examples + + +```txt title="clang.cmd" +@ECHO off +GOTO start +:find_dp0 +SET dp0=%~dp0 +EXIT /b +:start +SETLOCAL +CALL :find_dp0 +"C:\Users\ilg\AppData\Roaming\xPacks\@xpack-dev-tools\clang\17.0.6-2.1\.content\bin\clang.exe" %* +``` + +```txt title="clang.ps1" +#!/usr/bin/env pwsh +$basedir=Split-Path $MyInvocation.MyCommand.Definition -Parent + +$exe="" +if ($PSVersionTable.PSVersion -lt "6.0" -or $IsWindows) { + # Fix case when both the Windows and Linux builds of Node + # are installed in the same directory + $exe=".exe" +} +# Support pipeline input +if ($MyInvocation.ExpectingInput) { + $input | & "C:/Users/ilg/AppData/Roaming/xPacks/@xpack-dev-tools/clang/17.0.6-2.1/.content/bin/clang.exe" $args +} else { + & "C:/Users/ilg/AppData/Roaming/xPacks/@xpack-dev-tools/clang/17.0.6-2.1/.content/bin/clang.exe" $args +} +exit $LASTEXITCODE +``` diff --git a/website/docs/getting-started/_compatibility.mdx b/website/docs/getting-started/_compatibility.mdx index d719077..afed782 100644 --- a/website/docs/getting-started/_compatibility.mdx +++ b/website/docs/getting-started/_compatibility.mdx @@ -11,6 +11,10 @@ The **xpm** dependencies were separated from **npm** dependencies and policy [0001](/docs/user/policies/0001/) was introduced. +### v0.19.0 + +The Node.js base was increased to 18.0; no incompatibilities. + ### v0.20.0 The list of executable applications in binary xPacks was renamed from diff --git a/website/docs/guide/project-templates/index.mdx b/website/docs/guide/project-templates/index.mdx new file mode 100644 index 0000000..164c74f --- /dev/null +++ b/website/docs/guide/project-templates/index.mdx @@ -0,0 +1,53 @@ +--- + +title: Project templates +description: How to create projects that can be used as xpm project templates. +keywords: + - xpack + - xpm + - project + - template + +date: 2021-07-01 16:23:00 +0300 + +--- + +## Project templates + +**xpm** is able to create new projects based on templates. + +To be accepted as a template, a project must: + +- be an xpm package (have a `package.json` which includes an `xpack` property +- have a property called `main` in `package.json`, pointing to a JavaScript + file that can be consumed by `await import()` (formerly `require()`) +- the main file must export a class called `XpmInitTemplate` +- an instances of this class must have a `run()` method. +- have all dependencies bundled in (via `bundleDependencies`) + +The steps invoked by **xpm** to initialise a project from a template are: + +- call pacote to install the xPack in the global home folder +- identify the `main` property in `package.json` +- import the `XpmInitTemplate` class from the main JavaScript file by + invoking _require()_ +- instantiate the `XpmInitTemplate` class +- execute the `run()` method. + +The full code is in `init.js`, but a simplified version looks like this: + +```js + await pacote.extract(config.template, globalPackagePath, + { cache: cacheFolderPath }) + + const mainTemplatePath = path.join(globalPackagePath, globalJson.main) + + context.CliError = CliError + context.CliExitCodes = CliExitCodes + + const { XpmInitTemplate } = await import(mainTemplatePath) + const xpmInitTemplate = new XpmInitTemplate(context) + const code = await xpmInitTemplate.run() +``` + +TODO: add more diff --git a/website/docs/maintainer/_dependencies-details.mdx b/website/docs/maintainer/_dependencies-details.mdx new file mode 100644 index 0000000..cec3d10 --- /dev/null +++ b/website/docs/maintainer/_dependencies-details.mdx @@ -0,0 +1,34 @@ + +{/* ------------------------------------------------------------------------ */} + +Details about dependencies: + +- https://www.npmjs.com/package/@ilg/cli-start-options +- https://www.npmjs.com/package/@npmcli/arborist +- https://www.npmjs.com/package/@xpack/cmd-shim +- https://www.npmjs.com/package/@xpack/xpm-liquid +- https://www.npmjs.com/package/cacache +- https://www.npmjs.com/package/copy-file +- https://www.npmjs.com/package/cross-spawn +- https://www.npmjs.com/package/decompress +- https://www.npmjs.com/package/del +- https://www.npmjs.com/package/https-proxy-agent +- https://www.npmjs.com/package/is-windows +- https://www.npmjs.com/package/json +- https://www.npmjs.com/package/liquidjs +- https://www.npmjs.com/package/make-dir +- https://www.npmjs.com/package/mz +- https://www.npmjs.com/package/node-fetch +- https://www.npmjs.com/package/pacote +- https://www.npmjs.com/package/parse-git-config +- https://www.npmjs.com/package/proxy-from-env +- https://www.npmjs.com/package/semver +- https://www.npmjs.com/package/tar + +Details about devDependencies: + +- https://www.npmjs.com/package/del-cli +- https://www.npmjs.com/package/json +- https://www.npmjs.com/package/liquidjs +- https://www.npmjs.com/package/standard +- https://www.npmjs.com/package/tap diff --git a/website/docs/maintainer/index.mdx b/website/docs/maintainer/index.mdx index 89c2557..0ddb158 100644 --- a/website/docs/maintainer/index.mdx +++ b/website/docs/maintainer/index.mdx @@ -26,6 +26,8 @@ import customField from '@site/src/libs/customField'; import Prerequisites from '../developer/_common/_prerequisites.mdx'; import GetProjectSources from '../developer/_common/_get-project-sources.mdx'; +import DependenciesDetails from './_dependencies-details.mdx' + import More from './_more.mdx'; {/* ------------------------------------------------------------------------ */} @@ -88,10 +90,9 @@ kept as a legacy CommonJS dependency. up to date - commit the changes -Keep: -- [`@types/node`](https://www.npmjs.com/package/@types/node?activeTab=versions) - locked to latest that still matches the oldest supported node (18). + + ### Increase the version and update it in the top `package.json` diff --git a/website/docs/metadata/_shared/_dependencies-properties.mdx b/website/docs/metadata/_shared/_dependencies-properties.mdx new file mode 100644 index 0000000..e4ae2e3 --- /dev/null +++ b/website/docs/metadata/_shared/_dependencies-properties.mdx @@ -0,0 +1,44 @@ + +{/* ------------------------------------------------------------------------ */} + +There are two formats for defining the dependencies, the **extended** +format specific to **xpm**, and the **short** format, used for compatibility +with **npm**. + +When installing source packages into an **xpm** project, they are also added +to the `dependencies` list, in the extended format. + +## Properties + +In the **short** format, the dependency value is a **string**, with the same content as for **npm** dependencies. + +In the **extended** format, the value is an **object** with the following properties: + +### `specifier` + +A string that identifies the package. + +- a [SemVer](https://semver.org) expression: a package with a version that matches the expression +will be downloaded from the npmjs.com repository +- a full URI/URL: the package will be installed from the address +- `user/project`: a simplified syntax for GitHub projects, + +### `local` + +A string that defines the install strategy: + +- `link`: create a link in the local project pointing to a read-only instance of the package +- `copy`: create a full writable copy in the local project + +### `platforms` + +A string that indicates the platforms where the dependency can be installed. + +- `all`: install on all platforms +- `...`: comma separated list of platforms (linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64) + +:::note + +Currently the value is ignored by **npm install**. + +::: diff --git a/website/docs/metadata/actions/index.mdx b/website/docs/metadata/actions/index.mdx index a4e4e99..c879d78 100644 --- a/website/docs/metadata/actions/index.mdx +++ b/website/docs/metadata/actions/index.mdx @@ -12,16 +12,66 @@ date: 2024-11-21 21:36:00 +0300 # The `actions` definitions +## Purpose + +Define a map of sequences of shell commands to be invoked by name. + +## Syntax + +```json +{ + ... + "actions": { + ... + "": "" | [ "",... ], + ... + } + ... +} +``` + +The value of an `actions` entry can be either a string or an array +of strings containing shell commands. + +## Description + **xpm** actions are an extended version of **npm** scripts, that -supports multiple lines and substitutions. +support multiple lines and substitutions. `actions` can be defined at project level, or at build configuration level. -When actions are invoked for a specific a build configuration, the `actions` +When actions are invoked for a specific build configuration, the `actions` defined in the build configuration take precedence over `actions` with the same name defined at the project level. -Example: +:::caution Portability warning + +Special attention should be given to running shell commands on Windows. +While invoking simple applications is generally portable, many Unix +shell commands do not have direct equivalents on Windows. + +The solution is to use portable applications, for example instead of `rm` +use [`del-cli`](https://www.npmjs.com/package/del-cli), and so on. + +If full portability is not required, a workaround is to execute the +`xpm run` commands in a Git Bash terminal. + +::: + +## Multi-line actions + +In order to accommodate more complex actions, it is possible to define +sequences of commands as arrays of strings, with each line executed as +a separate command. + +If multiple commands are generated via loops, line terminators can be inserted +with `{{ os.EOL }}`), for example: + +```liquid +{% for command in package.xpack.my_commands %}{{ command }}{{ os.EOL }}{% endfor %} +``` + +## Example ```json {9,22} { diff --git a/website/docs/metadata/binaries/index.mdx b/website/docs/metadata/binaries/index.mdx index e685ba0..79544ae 100644 --- a/website/docs/metadata/binaries/index.mdx +++ b/website/docs/metadata/binaries/index.mdx @@ -12,62 +12,93 @@ date: 2024-11-21 21:36:00 +0300 # The `binaries` definitions -To keep packages small, binary xpm packages do not include the platform specific -binaries; instead they include only links -to the binary archives, and checksums to validate the downloads. +## Purpose -Example: +Define the URLs where the binary archives are stored. -```json {10,14,40} +## Syntax + +```json { - "name": "@xpack-dev-tools/cmake", - "version": "3.28.6-1.1", - "description": "A binary xpm package with the CMake executables", - "...": "...", - "xpack": { - "minimumXpmRequired": "0.16.3", + ... "binaries": { - "destination": "./.content", - "baseUrl": "https://github.com/xpack-dev-tools/cmake-xpack/releases/download/v3.28.6-1", - "skip": 1, - "platforms": { - "darwin-arm64": { - "fileName": "xpack-cmake-3.28.6-1-darwin-arm64.tar.gz", - "sha256": "a2f4f7d4963a3ee41ed3ef80a6dfed1e161b0b33b519fe2c4f11f4d9d310c36e" - }, - "darwin-x64": { - "fileName": "xpack-cmake-3.28.6-1-darwin-x64.tar.gz", - "sha256": "bafce78a57bab8c82268b32c0849ab875b437b90bed9bec83aad4c82af320103" - }, - "linux-arm": { - "fileName": "xpack-cmake-3.28.6-1-linux-arm.tar.gz", - "sha256": "d73889f852b310f974e20246775eb16b272384dbf6fdc236583395af40bf7b54" - }, - "linux-arm64": { - "fileName": "xpack-cmake-3.28.6-1-linux-arm64.tar.gz", - "sha256": "c80bd91b0e2b473d57b0ff30ea6ffc28480576946d6e69b65204f9d26dadfa52" - }, - "linux-x64": { - "fileName": "xpack-cmake-3.28.6-1-linux-x64.tar.gz", - "sha256": "b05343bda081b988b2c91896133b56ce286a8269c8550d986cc2e71a243684e1" - }, - "win32-x64": { - "fileName": "xpack-cmake-3.28.6-1-win32-x64.zip", - "sha256": "c1c07b1b51e0352e1fb1c9e6d87b743e975484df29f2a72c26d7385ad23fb679" + "destination": "", + "baseUrl": "", + "skip": , + "platforms": { + ... + "": { + "baseUrl": "", + "fileName": "", + "sha256": "" + }, + ... } - } - }, - "bin": { - "ccmake": "./.content/bin/ccmake", - "cmake": "./.content/bin/cmake", - "cpack": "./.content/bin/cpack", - "ctest": "./.content/bin/ctest" } - } } ``` -The `platforms` object define the location of platform specific archives. +## Description + +To keep packages small, binary xpm packages do not include the platform specific +binaries; instead they include only links +to the binary archives, and checksums to validate the downloads. + +The files are downloaded from `/`. The common +use case is to have all files published in the same folder; in this case it is +enough to define `baseUrl` once. However it is also possible to +download files from different folders/servers, by defining it +for each platform. + +The archives are unpacked in the `destination` folder, defined as relative +to the package root folder (usually `./.content`). + +To allow the archives to be manually expanded, the build scripts add an +initial folder with the package name and version +(like `xpack-arm-none-eabi-gcc-13.3.1-1.1`). + +To shorten the paths of extracted files, +**xpm** can skip this folder, or any number of initial +levels of folders in the archive, using the `skip` definition. + +## Properties + +### `destination` + +The value of the `destination` property is a string with a path relative +to the project top folder. + +The path is used in the `executables` definitions to refer to +the applications provided by the package. + +The default value is `./.content`. However, for readability reasons, +it is recommended to explicitly define it with this value. + +:::note + +All xPack Development Tools also use `./.content`. + +::: + +### `baseUrl` + +The value of the `baseUrl` property is a string with the base part +of the full URLs. It needs not have a trailing slash. + +This value and the `fileName` are used to determine the full URL. + +The `baseUrl` property can be use either in the top `binaries` object, +when it is used for all platforms, or in any `platform` object. + +### `skip` + +The value of the `skip` property is an integer, with the number of +folders that must be skipped when extracting the files from the archive. + +### `platforms` + +The `platforms` map has members that define the locations +of platform specific archives.
The platforms names @@ -92,18 +123,64 @@ The platform names are exactly those defined by Node.js, as
-The files are downloaded from `/`. The common -use case is to have all files published in the same folder; in this case it is -enough to define `baseUrl` once. However it is also possible to -download files from different folders/servers, by defining it -for each platform. +### `fileName` -The archives are unpacked in the `destination` folder, defined as relative -to the package root folder (usually `./.content`). +The value of the `fileName` property is a string with the name of the +archive. -To allow the archives to be manually expanded, the build scripts add an -initial folder with the package name and version -(like `xpack-arm-none-eabi-gcc-13.3.1-1.1`). +The supported archive extensions are: -To shorten the paths, **xpm** can skip this folder, or any number of initial -levels of folders in the archive, using the `skip` definition. +- `.tar.gz` to be used on macOS and GNU/Linux +- `.zip` to be used on Windows + +### `sha256` + +The value of the `sha256` property is a string containing the +[SHA](https://en.wikipedia.org/wiki/Secure_Hash_Algorithms) hash +of the archive. + +For security reasons, after downloading the archives, **xpm** verifies +this value and refuses to install the archive if the check fails. + +## Example + +```json {6-8,11-12} +{ + ... + "xpack": { + "minimumXpmRequired": "0.16.3", + "binaries": { + "destination": "./.content", + "baseUrl": "https://github.com/xpack-dev-tools/cmake-xpack/releases/download/v3.28.6-1", + "skip": 1, + "platforms": { + "darwin-arm64": { + "fileName": "xpack-cmake-3.28.6-1-darwin-arm64.tar.gz", + "sha256": "a2f4f7d4963a3ee41ed3ef80a6dfed1e161b0b33b519fe2c4f11f4d9d310c36e" + }, + "darwin-x64": { + "fileName": "xpack-cmake-3.28.6-1-darwin-x64.tar.gz", + "sha256": "bafce78a57bab8c82268b32c0849ab875b437b90bed9bec83aad4c82af320103" + }, + "linux-arm": { + "fileName": "xpack-cmake-3.28.6-1-linux-arm.tar.gz", + "sha256": "d73889f852b310f974e20246775eb16b272384dbf6fdc236583395af40bf7b54" + }, + "linux-arm64": { + "fileName": "xpack-cmake-3.28.6-1-linux-arm64.tar.gz", + "sha256": "c80bd91b0e2b473d57b0ff30ea6ffc28480576946d6e69b65204f9d26dadfa52" + }, + "linux-x64": { + "fileName": "xpack-cmake-3.28.6-1-linux-x64.tar.gz", + "sha256": "b05343bda081b988b2c91896133b56ce286a8269c8550d986cc2e71a243684e1" + }, + "win32-x64": { + "fileName": "xpack-cmake-3.28.6-1-win32-x64.zip", + "sha256": "c1c07b1b51e0352e1fb1c9e6d87b743e975484df29f2a72c26d7385ad23fb679" + } + } + }, + ... + } +} +``` diff --git a/website/docs/metadata/buildConfigurations/index.mdx b/website/docs/metadata/buildConfigurations/index.mdx index 6a6a20d..6d2b104 100644 --- a/website/docs/metadata/buildConfigurations/index.mdx +++ b/website/docs/metadata/buildConfigurations/index.mdx @@ -12,15 +12,51 @@ date: 2024-11-21 21:36:00 +0300 # The `buildConfigurations` definitions +## Purpose + +Define a map of build configurations. + +## Syntax + +```json +{ + ... + "buildConfigurations": { + ... + "": { + ... + "hidden": true, + "inherit": [ "",... ], + "dependencies": { ... }, + "devDependencies": { ... }, + "properties": { + ... + "": "": "" | [ "",... ], + ... + } + ... + } + } +} +``` + +## Description + During **development**, it is usual to build **separate debug and release -binaries**, with different configurations, like different preprocessor -macros, different compiler options, different optimisation levels, etc. +binaries**, with different configurations, such as preprocessor +macros, compiler options, and optimisation levels. -Extensive **testing** also requires building separate binaries, possible -targetted to **different architectures**, and using **different toolchains**, +Extensive **testing** also requires building separate binaries, +potentially targeting **different architectures**, and using +**different toolchains**, or even **different versions** of the same toolchain. -The build configurations address exactly this need, and allow to define +Build configurations address this need by allowing the definition **multiple different actions to run different builds and/or tests**. Build configurations can define their own `properties`, `actions`, @@ -33,12 +69,37 @@ To avoid redundant definitions, build configurations can **inherit** from one or more other build configurations, and redefine some of them, as needed. -A build configuration can inherit from multiple other build configurations. -The `inherit` array defines the list inherited build configurations; -the common definitions are collected in the listed order, with later -entries overriding earlier ones. +## Properties + +### `hidden` + +This boolean property is to be used by IDEs and has no functional +consequences. + +The mechanism that allows one build con + +### `inherit` + +The value of the `inherit` property is an array of strings with +build configuration names. + +The current build configuration inherits definitions from all +the build configurations listed by this property. + +The inheritance strategy uses overrides, so last definition override +previous ones. + +The definition collection is done in the given order, followed by local +definitions. + +## Other properties + +- [`dependencies`](../dependencies) +- [`devDependencies`](../devDependencies) +- [`properties`](../properties) +- [`actions`](../actions) -Example: +## Example ```json {8,26,31,46,54} { diff --git a/website/docs/metadata/dependencies/index.mdx b/website/docs/metadata/dependencies/index.mdx index c37a6f7..e134d70 100644 --- a/website/docs/metadata/dependencies/index.mdx +++ b/website/docs/metadata/dependencies/index.mdx @@ -10,6 +10,10 @@ date: 2024-11-21 21:36:00 +0300 --- +import DependenciesProperties from '../_shared/_dependencies-properties.mdx'; + +{/* ------------------------------------------------------------------------ */} + # The `dependencies` definitions ## Purpose @@ -20,22 +24,28 @@ Define the **xpm** source packages required at compile/link time. ```json { - "xpack": { + ... "dependencies": { - ... + "": "semver" | { + "specifier": "", + "local": "link" | "copy", + "platforms": ",..." + }, + ... } - } + ... } ``` ## Description The `dependencies` definition is similar to the **npm** -[definition](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#dependencies), +[definition](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#dependencies) but lists the **xpm** source packages required at compile/link time. When a source package is installed locally into the -local project `xpacks` folder (without `--global`), all packages listed in its `xpack.dependencies` +local project's `xpacks` folder (without `--global`), all packages listed +in its `xpack.dependencies` are also recursively installed into the same local `xpacks` folder. In other words, the list of source dependencies is linearised, @@ -50,51 +60,11 @@ dependencies is the main difference compared to **npm**. **npm**, designed for JavaScript/TypeScript, maintains the hierarchical structure of dependencies, which is -not suitable for compiled languages +not suitable for compiled languages. ::: -There are two formats for defining the dependencies, the **extended** -format specific to **xpm**, and the **short** format, used for compatibility -with **npm**. - -When installing source packages into an **xpm** project, they are also added -to the `dependencies` list, in the extended format. - -## Properties - -In the **short** format, the dependency value is a **string**, with the same content as for **npm** dependencies. - -In the **extended** format, the value is an **object** with the following properties: - -### `specifier` - -A string that identifies the package. - -- a [SemVer](https://semver.org) expression: a package with a version that matches the expression -will be downloaded from the npmjs.com repository -- a full URI/URL: the package will be installed from the address -- `user/project`: a simplified syntax for GitHub projects, - -### `local` - -A string that defines the install strategy: - -- `link`: create a link in the local project pointing to a read-only instance of the package -- `copy`: create a full writable copy in the local project - -### `platforms` - -A string that indicates the platforms where the dependency can be installed. - -- `all`: install on all platforms -- `...`: comma separated list of platforms (linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64) - -:::note - -Currently the value is ignored by **npm install**. - -::: + ## Examples diff --git a/website/docs/metadata/devDependencies/index.mdx b/website/docs/metadata/devDependencies/index.mdx index f362f74..523bb9e 100644 --- a/website/docs/metadata/devDependencies/index.mdx +++ b/website/docs/metadata/devDependencies/index.mdx @@ -10,6 +10,10 @@ date: 2024-11-21 21:36:00 +0300 --- +import DependenciesProperties from '../_shared/_dependencies-properties.mdx'; + +{/* ------------------------------------------------------------------------ */} + # The `devDependencies` definitions ## Purpose @@ -20,18 +24,23 @@ Define the **xpm** packages required during development. ```json { - "xpack": { + ... "devDependencies": { - ... + "": "semver" | { + "specifier": "", + "local": "link" | "copy", + "platforms": ",..." + }, + ... } - } + ... } ``` ## Description The `devDependencies` definitions is similar to the **npm** -[definition](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#devdependencies), +[definition](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#devdependencies) but lists the **xpm** definitions required during the development of the current package, usually executables and other tools. @@ -52,6 +61,8 @@ The formats are identical to those used by [`dependencies`](../dependencies/). When installing binary packages into an **xpm** project, they are also added to the `devDependencies` list, in the extended format. + + ## Example Extended format development dependency: diff --git a/website/docs/metadata/executables/index.mdx b/website/docs/metadata/executables/index.mdx index 2d393a5..1e41216 100644 --- a/website/docs/metadata/executables/index.mdx +++ b/website/docs/metadata/executables/index.mdx @@ -12,16 +12,35 @@ date: 2024-11-21 21:36:00 +0300 # The `executables` definitions -:::info +## Purpose -This definition was added in November 2024, in version 0.19.5. +List the executables available in the binary archive. -The previous name was `bin`, which is kept for compatibility reasons. +## Syntax -::: +```json +{ + ... + "executables": { + .... + "": "", + .... + } +} +``` + +## History + +### 0.19.5 / November 2024 + +Added. -When installing a package with executables, -after the archive is unpacked, links to all executables listed +At the same moment the previous name `bin` was deprecated, but still preserved. + +## Description + +When installing a binary package with executables, +after the archive is extracted, links to all executables listed in the `executables` object are created in the `xpacks/.bin` folder. On Windows, where soft links to files are problematic, `.cmd` forwarders/shims are created. @@ -34,3 +53,22 @@ explicity launch the xPack executables via an explicit shell like `cmd.exe` or `PowerShell.exe`. ::: + +## Example + +```json {8-11} +{ + ... + "xpack": { + ... + "destination": "./.content", + ... + "executables": { + "ccmake": "./.content/bin/ccmake", + "cmake": "./.content/bin/cmake", + "cpack": "./.content/bin/cpack", + "ctest": "./.content/bin/ctest" + } + } +} +``` diff --git a/website/docs/metadata/index.mdx b/website/docs/metadata/index.mdx index 3b04f50..bfea64d 100644 --- a/website/docs/metadata/index.mdx +++ b/website/docs/metadata/index.mdx @@ -68,11 +68,11 @@ contain the following definitions: ## Objects and arrays +- [`actions`](./actions/) +- [`binaries`](./binaries/) +- [`buildConfigurations`](./buildConfigurations/) - [`dependencies`](./dependencies/) - [`devDependencies`](./devDependencies/) -- [`binaries`](./binaries/) - [`executables`](./executables/) - [`properties`](./properties/) -- [`actions`](./actions/) -- [`buildConfigurations`](./buildConfigurations/) diff --git a/website/docs/metadata/liquidjs-substitutions/index.mdx b/website/docs/metadata/liquidjs-substitutions/index.mdx index 06a188b..2fd600d 100644 --- a/website/docs/metadata/liquidjs-substitutions/index.mdx +++ b/website/docs/metadata/liquidjs-substitutions/index.mdx @@ -12,14 +12,18 @@ date: 2024-11-21 21:36:00 +0300 # LiquidJS substitutions -An additional feature compared to **npm** is a powerful -substitution engine that can be used in all **xpm** -metadata definitions. +To increase reusability, it is possible to use **substitutions** +in in all **xpm** +metadata definitions. The syntax is more elaborate than the simple +variable substitution, and is using the +[LiquidJS](https://liquidjs.com/) template engine syntax, +which accepts the full LiquidJS syntax. -It is implemented using the -[LiquidJS](https://liquidjs.com) engine. -The full LiquidJS syntax is supported, with all **tags** and **filters**, -plus some custom filters, presented below. +The LiquidJS definitions are: + +- **variables**, like `{{ configuration.name }}` +- **filters**, like `{{ configuration.name | downcase }}` +- **tags**, like `{% if os.platform != 'win32' %}xpm run execute --config synthetic-posix-cmake-debug{% endif %}` For more details, please see the documentation for the [`xpack/xpm-liquid-ts`](https://xpack.github.io/xpm-liquid-ts) module, where @@ -117,3 +121,11 @@ the following **xpm** specific filters are also available: - `to_posix_filename` - `to_win32_filename` +### Multi-line definitions + +If multiple lines are generated via loops, line terminators can be inserted +with `{{ os.EOL }}`), for example: + +```liquid +{% for command in package.xpack.my_commands %}{{ command }}{{ os.EOL }}{% endfor %} +``` diff --git a/website/docs/metadata/minimumXpmRequired/index.mdx b/website/docs/metadata/minimumXpmRequired/index.mdx index c69d977..5aeef55 100644 --- a/website/docs/metadata/minimumXpmRequired/index.mdx +++ b/website/docs/metadata/minimumXpmRequired/index.mdx @@ -26,10 +26,9 @@ Identify the minimum required **xpm** version. ```json { - ... - "xpack": { + ... "minimumXpmRequired": "" - } + ... } ``` @@ -47,9 +46,10 @@ If missing, no checks are performed on the **xpm** version. ```json {4} { - ... - "xpack": { - "minimumXpmRequired": "0.19.4" - } + ... + "xpack": { + "minimumXpmRequired": "0.19.4" + ... + } } ``` diff --git a/website/docs/metadata/properties/index.mdx b/website/docs/metadata/properties/index.mdx index f23aea6..db407f3 100644 --- a/website/docs/metadata/properties/index.mdx +++ b/website/docs/metadata/properties/index.mdx @@ -12,7 +12,28 @@ date: 2024-11-21 21:36:00 +0300 # The `properties` definitions -The `properties` map allows to define string properties that can +## Purpose + +Define the values used as variables in the LiquidJS substitutions. + +## Syntax + +```json +{ + ... + "properties": { + ... + "": "", + ... + } +} +``` + +The value of `properties` is a map of string definitions. + +## Description + +The `properties` map is used to define string properties that can be used as substitution variable in other definitions. `properties` can be defined on top of other `properties`, and the LiquidJS @@ -22,35 +43,39 @@ When substitutions occur within a build configuration, the `properties` defined in the build configuration take precedence over `properties` with the same name defined at the project level. -Examples: +## Examples -```json title="Project properties" {4} +Project properties: + +```json {4} { - "xpack": { - "properties": { - "buildFolderRelativePath": "{{'build' | path_join: configuration.name | to_filename | downcase}}", + "xpack": { + "properties": { + "buildFolderRelativePath": "{{'build' | path_join: configuration.name | to_filename | downcase}}", + } } - } } ``` -```json title="Build configuration properties" {6,12,13} +Build configuration properties: + +```json {6,12,13} { - "name": "@xpack-dev-tools/cmake", - "version": "3.28.6-1.1", - "xpack": { - "properties": { - "appLcName": "cmake", - }, - "buildConfigurations": { - "common-docker": { - "hidden": true, + "name": "@xpack-dev-tools/cmake", + "version": "3.28.6-1.1", + "xpack": { "properties": { - "containerName": "{{properties.appLcName}}-{{package.version}}-{{configuration.name}}", - "force32": "" + "appLcName": "cmake", + }, + "buildConfigurations": { + "common-docker": { + "hidden": true, + "properties": { + "containerName": "{{properties.appLcName}}-{{package.version}}-{{configuration.name}}", + "force32": "" + } + } } - } } - } } ``` diff --git a/website/package.json b/website/package.json index d77c5b4..dd919fd 100644 --- a/website/package.json +++ b/website/package.json @@ -60,6 +60,7 @@ "websiteConfig": { "shortName": "xpm", "longName": "xPack Project Manager", + "programName": "xpm", "title": "xpm - The xPack Project Manager", "tagline": "A tool to automate builds, tests and manage C/C++ dependencies, inspired by npm", "metadataDescription": "The xPack Project Manager command line tool", diff --git a/website/sidebar-docs-custom.ts b/website/sidebar-docs-custom.ts index 7e457e1..d640886 100644 --- a/website/sidebar-docs-custom.ts +++ b/website/sidebar-docs-custom.ts @@ -97,38 +97,38 @@ export const customDocsSidebar = [ }, { type: 'doc', - id: 'metadata/dependencies/index', - label: 'dependencies' + id: 'metadata/actions/index', + label: 'actions' }, { type: 'doc', - id: 'metadata/devDependencies/index', - label: 'devDependencies' + id: 'metadata/binaries/index', + label: 'binaries' }, { type: 'doc', - id: 'metadata/binaries/index', - label: 'binaries' + id: 'metadata/buildConfigurations/index', + label: 'buildConfigurations' }, { type: 'doc', - id: 'metadata/executables/index', - label: 'executables' + id: 'metadata/dependencies/index', + label: 'dependencies' }, { type: 'doc', - id: 'metadata/properties/index', - label: 'properties' + id: 'metadata/devDependencies/index', + label: 'devDependencies' }, { type: 'doc', - id: 'metadata/actions/index', - label: 'actions' + id: 'metadata/executables/index', + label: 'executables' }, { type: 'doc', - id: 'metadata/buildConfigurations/index', - label: 'buildConfigurations' + id: 'metadata/properties/index', + label: 'properties' }, ] }, @@ -148,12 +148,28 @@ export const customDocsSidebar = [ }, ] }, + { + type: 'doc', + id: 'guide/project-templates/index', + label: 'Project templates' + }, ] }, { - type: 'doc', - id: 'developer/index', - label: 'Contributor\'s Guide' + type: 'category', + label: 'Contributor\'s Guide', + link: { + type: 'doc', + id: 'developer/index', + }, + collapsed: true, + items: [ + { + type: 'doc', + id: 'developer/windows-symbolic-links/index', + label: 'Windows symbolic links' + }, + ] }, { type: 'doc',