From 5c4af29310a198025cca36e70f9756676842a285 Mon Sep 17 00:00:00 2001 From: Liviu Ionescu Date: Mon, 16 Dec 2024 21:27:28 +0200 Subject: [PATCH] website update --- .../docs/developer/js-style-guide/index.mdx | 39 +- .../docs/developer/new-xpack-git/index.mdx | 637 ------------------ .../docs/getting-started/glossary/index.mdx | 12 +- .../getting-started/prerequisites/index.mdx | 10 +- website/docs/project/about/_custom-about.mdx | 4 +- website/docs/project/about/_website.mdx | 2 +- website/docs/project/history/index.mdx | 273 ++++---- website/sidebar-docs-custom.ts | 65 +- 8 files changed, 196 insertions(+), 846 deletions(-) delete mode 100644 website/docs/developer/new-xpack-git/index.mdx diff --git a/website/docs/developer/js-style-guide/index.mdx b/website/docs/developer/js-style-guide/index.mdx index 19a81be..af77cd2 100644 --- a/website/docs/developer/js-style-guide/index.mdx +++ b/website/docs/developer/js-style-guide/index.mdx @@ -12,42 +12,39 @@ date: 2017-10-09 02:47:00 +0300 :::info -Given the positive experience with -TypeScript while writing the VS Code xPack extension, starting with 2021, -existing JavaScript projects will be migrated to TypeScript. +Given the positive experience with TypeScript while writing the +VS Code xPack extension, starting in 2021, existing JavaScript +projects will be migrated to TypeScript. ::: ## Standard TS/JS -After many years dealing with style guides for various languages, -the conclusion is that the style itself is less important than applying -it consistently. +After many years of working with style guides for various languages, +the conclusion is that the specific style is of lesser importance; +what matters more is its consistent application. -So, for the xPack JavaScript source files to be consistent, the first -requirement is to pass the [Standard JS](https://standardjs.com) +To ensure consistency in the xPack JavaScript source files, the +primary requirement is to pass the [Standard JS](https://standardjs.com) validation tools, which also have a TypeScript variant -([ts-standard](https://www.npmjs.com/package/ts-standard)) +([ts-standard](https://www.npmjs.com/package/ts-standard)). -After this, the main recommendations are: +Following this, the main recommendations are: -- use the **ECMAScript 6** specifications (ES 6), -- if the module does something reasonably complex, the module public -functions **must be asynchronous**, -- asynchronous functions must **use promises** (and definitely -**avoid callbacks**), -- **reentrancy** should be seriously considered (avoid module-global variables). +- Utilise the ECMAScript 6 specifications (ES 6). +- If the module performs reasonably complex tasks, its public functions **must be asynchronous**. +- Asynchronous functions should **use promises** (and definitely **avoid callbacks**). +- **Reentrancy** should be carefully considered (avoid module-global variables). ## The xPack project preferences -### Prefer TypeScript to JavaScript +### Prefer TypeScript over JavaScript -This is Rule no. 1, that overrides all other rules. +This is Rule No. 1, which overrides all other rules. -If JavaScript code must be -still used in some places, prefer ES6 solution. +If JavaScript code must still be used in some instances, prefer ES6 solutions. -Definitely **avoid using old style code**. +Definitely **avoid using old-style code**. ### Use classes as much as possible diff --git a/website/docs/developer/new-xpack-git/index.mdx b/website/docs/developer/new-xpack-git/index.mdx deleted file mode 100644 index b19b770..0000000 --- a/website/docs/developer/new-xpack-git/index.mdx +++ /dev/null @@ -1,637 +0,0 @@ ---- -title: How to create a new xPack Git repository - -date: 2019-07-09 17:48:00 +0300 - ---- - -# How to create a new xPack Git repository - -## Overview - -The technical definition of an xPack is _a folder which includes a -package.json file with some minimal content_ -([full definition](/docs/getting-started/)); -it does not require -any special structure for the folders or for the version-control system, -if any. - -### Projects with 3rd party content - -The first thought is that xPacks, as a new technology, -will be used for new projects, -with original content, so, in principle, these projects can be created -to have any structure. - -In reality there are lots of existing 3rd party -software projects, each using its specific structure, and migrating them to -xPacks may add some maintenance burden to keep them in sync with the -originals. - -### The `xpack` branch and three-way merging - -One way to reduce the maintenance burden of source xPacks is to use the -[three-way merge](https://en.wikipedia.org/wiki/Merge_(version_control)#Three-way_merge) -feature of Git and a separate branch to accommodate the xPack specific changes. - -This method does not require any changes to the original project, which can -keep its original structure, with its original branches, regardless -their names. - -The only requirement is to create a new branch (preferably named `xpack`) -and to keep the changes on it; thus the main branch (probably `master`) can -easily track the upstream repository, while the xPack specific changes -continue to be developed using the `xpack` branch; from time to time the -main branch can be merged into the `xpack` branch and things kept in sync. - -:::note - -The xPack tools do not require and -do not enforce the use of a branch named `xpack`, this is only -a recommendation. - -::: - -## Create a source library xPacks with 3rd party content - -### Projects without a public repository - -If the 3rd party project does not use a public repository, -it is necessary to create one. - -For projects distributed as archives, to simplify maintenance, -it is recommended to reconstruct the history in a separate branch -(like `originals`) by adding commits with the content of each released -archive. - -Follow the steps to create a new repository, and watch for the extra steps to -create the `originals` branch. - -### Projects with existing Git - -If the 3rd party project uses a public Git: - -#### Fork - -With the GitHub web interface: - -- select the upstream project -- fork it, for example in the - [3rd party xPacks](https://github.com/xpack-3rd-party) organization) -- preferably rename it: - - add a prefix with the name of the original organization - - add the `-xpack` suffix - - click the **Rename** button -- select the **Settings** tab - - in the **Features** section - - disable **Wikis** - - enable **Issues** - - enable **Sponsorship** (if needed) - - disable **Projects** - - enable **Discussions**, Set up discussions - - quit the **Settings** tab (there is no Save) - -#### Clone locally - -Clone the project locally on the development machine: - -With the GitHub web interface: - -- open the forked project -- select the **Code** tab -- click the **Clone or download** button -- click Open with GitHub Desktop; save to a folder like - `xpack-3rd-party/-xpack.git` - -#### Identify the latest release - -With VS Code, Fork or Git: - -- identify the stable branch -- identify the latest release tag -- reset the current branch to the tagged commit - -#### Create the `xpack` branch - -With VS Code, Fork or Git: - -- select the tagged commit -- create new branch `xpack` -- switch to it - -Continue from the **Common steps** section below. - -## Create a new xPack repository - -If the project does not already have a forked repository, create a new -Git project. - -:::note - -For consistency reasons, it is -recommended for the new xPacks, even if -they do not include 3rd party content, to use the `xpack` branch instead -of the `master` branch. - -::: - -:::caution - -Do not use a GitHub Template project! -The easiest way to create new projects would be to use an existing -GitHub Template project. Unfortunately, at the time of testing, -the repositories resulted -by using this method had weird histories, -like disconnected commits; until this will be fixed, -this method is not recommended. - -::: - -### Create the Git project - -The following steps apply to GitHub. Adjust them for other Git hosting sites. - -The editor of choice is Visual Studio Code (VS Code), but you can use -any editor you like; just be sure that on Windows it does not mess the -line terminators. - -:::tip - -To easily identify the project as -an xPack, it is recommended to suffix the project name with '-xpack'. - -::: - -With a browser, at GitHub, select your account or organisation. -(for the purposes of this project, here are some organisations that use xPacks: -[xPacks Dev Tools](https://github.com/xpack-dev-tools/), -[µOS++](https://github.com/micro-os-plus/), -[3rd party source xPacks](https://github.com/xpack-3rd-party/)). - -- click the green **New** button to create a new repository - - enter **Repository name**; use all lowercase and hyphens to - separate words (not underscores!); preferably suffix the name with `-xpack` - - enter **Description** (like _A source xPack with ..._ or _A binary xPack with ..._; no ending dot!) - - select **Public** - - enable **Initialize this repository with a README** - - select **Add .gitignore: Node** - - select **Add a license: MIT License**; this is the license of - choice for xPacks, but any other license of your choice is also ok - - click the **Create Repository** button -- select the **Settings** tab - - in the **Features** section - - disable **Wikis** - - enable **Sponsorship** (if needed) - - disable **Projects** - - enable **Discussions** - - quit the **Settings** tab (there is no Save) - -### Clone the repository to a local folder - -With the GitHub web interface: - -- open the project -- select the **Code** tab -- click the **Clone or download** button; this will open a - small **Clone to HTTPS** window -- click the **Copy** icon, or explicitly copy the URL -- in a terminal window, in a place of our choice, create a folder - to store all xPacks (for example it can be named `xPacks`): - -```sh -mkdir -p xPacks -cd xPacks -git clone https://github.com//.git .git -``` - -### Edit the master `README.md` file - -As mentioned in the introduction, -although for original xPacks there are no constraints on how to -organise the branches, for consistency with xPacks that use 3rd -party content, it is recommended to use an `xpack` branch. - -In this case, to warn users about this configuration, edit -the `README.md` file; keep the header line and replace the content with: - -```text -This project does not use the `master` branch, please -switch to the `xpack` branch to get the project files. -``` - -With VS Code, Fork or Git: - -- stage the `README.md` file -- commit with the following message: **README: 'no master' notice** - -### Edit the `LICENSE[-XPACK]` file - -The automatically generated `LICENSE` file already includes the -user name as the copyright owner. When the project is owned by -an organisation, the name refers to the organisation. Probably -this is not exactly what you need, and you might prefer to have -your name in the copyright notice. - -Check and possibly adjust to match your `LICENSE` requirements. - -```text -MIT License - -Copyright (c) 2022 Liviu Ionescu - -Permission is hereby granted, free of charge, to any person obtaining a copy -... -``` - -With VS Code, Fork or Git: - -- for 3rd party content, rename it to `LICENSE-XPACK` -- stage the file -- commit with the following message: **LICENSE: update copyright owner** - -### Create the `originals` branch - -For a 3rd party project that does not use a -public Git project, but is distributed only as release archives, to -keep track of the changes it is recommended to -recreate the Git with the original -code on a separate branch, like `originals`, and later treat it -as the `master` branch. - -With each upstream release, while on the `originals` branch, -fully remove the content and extract the newly released archive. - -Then merge the update `originals` branch into the `xpack` branch. - -In case the archive contains binary files, or other large files considered -not essential for the xPack distribution, add them to `.gitignore`. - -Add/Edit the README file to add: - -```text -This branch is used to recreate the 3rd party project history -from release archives. -``` - -Commit with the following message: **README: notice for 3rd party content** - -### Create the `xpack` branch - -With VS Code, Fork or Git: - -- select the `master` branch -- create new branch `xpack` -- switch to it - -## Common steps - -### Edit the `.gitignore` file - -With VS Code: - -- add the following to `.gitignore`: - -```text - -# added for xPack - -.vscode/c_cpp_properties.json - -# xpm -xpacks/ -build*/ - -/*.tgz - -# Windows -Thumbs.db - -# macOS -.DS_Store - -# end -``` - -- for Eclipse C/C++ projects you can include: - -```text -# Eclipse -.settings/ -Debug/ -Release/ -``` - -With VS Code, Fork or Git: - -- stage the `.gitignore` file -- commit with the following message: **.gitignore: add xPack specifics** - -### Add the `.npmignore` file - -With VS Code, create a new file with: - -```text - -.DS_Store -.git/ -.github/ -.gitignore -.gitmodules -.clang-* -.cmake-format - -.vscode/ - -patches/ -pkgconfig/ -scripts/ -test*/ -build*/ -ci/ -docs/ -example*/ - -xpacks/ -node_modules/ - -/*.tgz - -README-* -LICENSE-* -CONTRIBUTING** -``` - -- update the content until `npm pack` shows only the desired content -- stage the `.npmignore` file -- commit with the following message: **.npmignore preliminary content** - -### Publish all branches - -With VS Code, Fork or Git: - -- push all local branches (`master`, `xpack` and maybe the `originals`) - -### Change the default branch to `xpack` - -With the GitHub web interface: - -- open the project -- select the **Settings** tab -- select the **Branches** grouping -- change the **Default branch** to `xpack` -- click the **Update** button -- click the **I understand, update the default branch** confirmation window - -### Create the npm/xpm `package.json` - -Select the `xpack` branch. - -Use `xpm init` and later edit the `package.json`. - -```console -$ cd .git -$ xpm init --verbose -$ cat package.json -{ - "name": "@/", - "version": "0.1.0", - "description": "A source/binary xPack with ", - "main": "", - "scripts": { - "test": "echo \"Error: no test specified\" && exit 1" - }, - "repository": { - "type": "git", - "url": "https://github.com//-xpack.git" - }, - "bugs": { - "url": "https://github.com//-xpack/issues" - }, - "homepage": "https://github.com//-xpack", - "keywords": [ - "xpack" - ], - "author": { - "name": "", - "email": "", - "url": "" - }, - "license": "MIT", - "config": {}, - "dependencies": {}, - "devDependencies": {}, - "xpack": {} -} -$ -``` - -Open `package.json` with VS Code: - -- as **name** enter the scope (your npm account name or one of - your npm organisations) and the project name, without `-xpack.git` - (like `@micro-os-plus/diag-trace`, `@xpack-dev-tools/ninja-build`, - `@xpack-3rd-party/arm-cmsis-core`) -- as **version**, enter `0.1.0` if the project is in early development, - or accept 1.0.0 for the first stable release; generally use the - [semver](https://semver.org) conventions -- as **description**, use the same string as the GitHub project description -- in **scripts**, check and possibly remove a trailing comma, -- as **url** and **homepage**, use the actual project Git URL -- as **author**, enter full data, like - -```json -{ - "author": { - "name": "Liviu Ionescu", - "email": "ilg@livius.net", - "url": "https://github.com/ilg-ul/" - } -} -``` - -- as **license**, enter the [SPDX](https://spdx.org/licenses/) license - identifier (like `MIT`); if the license is not a standard one, provide - the text in a `LICENSE` file and update the JSON to read: - -```json -{ "license": "SEE LICENSE IN " } -``` - -- if the package is inspired by other existing code, enter the author - as the first contributor, for example: - -```json -{ - "contributors": [ - { - "name": "SEGGER Microcontroller GmbH & Co. KG", - "email": "support@segger.com", - "url": "https://www.segger.com/", - "git": "https://github.com/boost-ext/ut.git", - "license": "..." - } - ], - "...": "..." -} -``` - -Update the list of npm scripts: - -```json -{ - "scripts": { - "npm-install": "npm install", - "pack": "npm pack", - "version-patch": "npm version patch", - "version-minor": "npm version minor", - "postversion": "git push origin --all && git push origin --tags", - "git-log": "git log --pretty='%cd * %h %s' --date=short" - }, - "...": "..." -} -``` - -### Commit the initial package file - -With VS Code, Fork or Git: - -- stage the `package.json` -- commit with the following message: **package.json: v0.1.0** - -### Edit the `README.md` file with actual content - -With the editor of your choice: - -- start with some badges -- as headers, you can start with H1, the npmjs server now shows it -- after the main title, copy the project description -- explain how to install the xPack - (like `xpm install --global @scope/name`) -- in the License section, use something like - -```markdown -### 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/). -``` - -With VS Code, Fork or Git: - -- stage the `README*.md` files -- commit with the following message: **README: preliminary content** - -### Add README-MAINTAINER[-XPACK].md - -Create or copy/paste from a similar project, or from the template available -in the `build-helper-xpack` project. - -For 3rd party projects, suffix the name with `-XPACK`. - -With VS Code, Fork or Git: - -- stage the `README-MAINTAINER.md` files -- commit with the following message: **README-MAINTAINER: preliminary content** - -### Add a CHANGELOG[-XPACK].md file - -A possible content: - -```md -# Change & release log - -Releases in reverse chronological order. - -Please check -[GitHub](https://github.com/micro-os-plus/micro-test-plus-xpack/issues/) -and close existing issues and pull requests. - -## 2022-01-03 - -* v2.0.5 -``` - -With VS Code, Fork or Git: - -- stage the `CHANGELOG.md` files -- commit with the following message: **CHANGELOG: preliminary content** - -### Add .github/workflows/* - -Copy/paste files like: - -- `CI.yml` -- `test-all.yml` - -- commit with the following message: **.github/workflows preliminary content** - -For projects with an upstream Git, disable existing workflows. - -### Publish the initial version to GitHub - -With VS Code, Fork or Git: - -- click the **Push** button (to push the `xpack` branch to the server) - -### Add more content - -- add project files -- copy/paste the `tests[-xpack]` folder - -### Commit the initial content - -With VS Code, Fork or Git: - -- stage the new files -- commit with the following message: **add initial content** - -### Create the `xpack-develop` branch - -With VS Code, Fork or Git: - -- select the `xpack` branch -- create the `xpack-develop` branch - -Generally work in the `xpack-develop` branch and only when ready merge it -to `master`. - -### Publish the branches to GitHub - -With VS Code, Fork or Git: - -- **Push** all branches (or at least `xpack` and `xpack-develop`) - -### Publish the initial version to the npmjs public registry - -- check the latest commits `npm run git-log` -- update `CHANGELOG.md`; commit with a message like - _CHANGELOG: prepare npm v1.10.0-1.1_ -- `npm version v1.10.0-1.1`; the first 4 numbers are the same as the - GitHub release; the fifth number is the npm specific version -- `npm pack` and check the content of the archive, which should list -only the desired content and -the `package.json`, the `README.md`, `LICENSE` and `CHANGELOG.md` files -- push all changes to GitHub -- `npm publish --access public --tag next` - -When the release is considered stable, promote it as `latest`. For example: - -- `npm dist-tag ls @xpack-dev-tools/ninja-build` -- `npm dist-tag add @xpack-dev-tools/ninja-build@1.10.0-1.1 latest` -- `npm dist-tag ls @xpack-dev-tools/ninja-build` - -### Bump version - -In general, depending on the _disruption_ degree, chose one of the following: - -```sh -cd .git -npm version patch -npm version minor -npm version major -``` - -With VS Code, Fork or Git: - -- **Push** the commits diff --git a/website/docs/getting-started/glossary/index.mdx b/website/docs/getting-started/glossary/index.mdx index 8379708..f08c716 100644 --- a/website/docs/getting-started/glossary/index.mdx +++ b/website/docs/getting-started/glossary/index.mdx @@ -8,9 +8,9 @@ title: Glossary ### xPack **xPack** stands for **xpm package**. It is a npm package with an additional -`xpack` definitions to store the **xpm** extra configurations. +`xpack` definitions to store the **xpm** metadata. -It is also used as a generic name for the top project (**The xPack Reproducible Build Framework**, or, in short **The xPack Project**). +It is also used as a **generic name** for the top project (**The xPack Reproducible Build Framework**, or, in short **The xPack Project**). ### xpm @@ -21,13 +21,13 @@ compiled languages like C/C++. ### npm -Although not officially acknowledged by the existing documentation, **npm** +Although the existing documentation does not acknowledge the acronym, **npm** is the Node.js package manager. ### Node.js **Node.js** is a cross-platform, open-source JavaScript runtime -environment. +environment for CLI applications. ### CLI @@ -49,7 +49,7 @@ by eCos and is documented in [The eCos Component Writer's Guide](http://ecos.sou ### xCDL **xCDL** is the xPack Configuration Definition Language and framework, -inspired by CDL +inspired by CDL. ### Cross-platform tool @@ -70,7 +70,9 @@ identical results. A platform-dependent folder within the home folder where **xpm** installs all versions of the packages. +{/* ### System global xPacks store A platform-dependent folder within in a system location where **xpm** installs all versions of the packages. (currently not yet implemented) +*/} diff --git a/website/docs/getting-started/prerequisites/index.mdx b/website/docs/getting-started/prerequisites/index.mdx index b9c9f0a..196dea5 100644 --- a/website/docs/getting-started/prerequisites/index.mdx +++ b/website/docs/getting-started/prerequisites/index.mdx @@ -36,17 +36,17 @@ import VersionManager from './_version-manager.mdx'; ## Overview -All xPack Core Tools are [Node.js](https://nodejs.org) CLI application +All xPack core tools are [Node.js](https://nodejs.org) CLI application available from the -[npmjs.com](https://www.npmjs.com) public repository. They are installed -via `npm` which runs on top of **Node.js**. +[npmjs.com](https://www.npmjs.com) public repository. They can be installed +via `npm`, which runs on top of **Node.js**. ## Install Node.js & npm -The only xPack prerequisite is a recent +The only prerequisite for xPack is a recent version of [Node.js](https://nodejs.org) (>=**{customField('enginesNodeVersion')}**), as some dependencies require new features. Detailed instructions -for each supported platform are provided in the next sections. +for each supported platform are provided in the following sections. { `$ node --version diff --git a/website/docs/project/about/_custom-about.mdx b/website/docs/project/about/_custom-about.mdx index 3b246a3..3413228 100644 --- a/website/docs/project/about/_custom-about.mdx +++ b/website/docs/project/about/_custom-about.mdx @@ -4,6 +4,6 @@ The **xPack Project** serves as an umbrella for various individual projects, including tools, npm modules, and platform-specific executables. All these projects are hosted on -GitHub under two -_organizations_: [xpack](https://github.com/xpack/) and +GitHub under two groups (or +_organizations_ in GitHub parlance): [xpack](https://github.com/xpack/) and [xpack-dev-tools](ttps://github.com/xpack-dev-tools/). diff --git a/website/docs/project/about/_website.mdx b/website/docs/project/about/_website.mdx index ddd729e..2787061 100644 --- a/website/docs/project/about/_website.mdx +++ b/website/docs/project/about/_website.mdx @@ -11,4 +11,4 @@ more elaborated theme, [Jekyll Doc Theme 6.0](https://idratherbewriting.com/documentation-theme-jekyll/) by [Tom Johnson](https://github.com/tomjoht). - + diff --git a/website/docs/project/history/index.mdx b/website/docs/project/history/index.mdx index c4576a2..d518126 100644 --- a/website/docs/project/history/index.mdx +++ b/website/docs/project/history/index.mdx @@ -19,9 +19,9 @@ of the **eCos CDL** was written. The history of the **xPack** project was deeply intertwined with [the history of µOS++](http://micro-os-plus.github.io/project/history/), -as it was initially intended to **automate building** and running +as it was initially intended to **automate the building** and running **multi-platform unit tests** for [µOS++](http://micro-os-plus.github.io). -Later it was also used to build the binary xPacks, which further +Later, it was also used to build the binary xpm packages, which further validated the concept. To avoid redundancy, the full story is not replicated here, so please @@ -29,80 +29,79 @@ read [the history of µOS++](http://micro-os-plus.github.io/project/history/) before continuing; the brief list of the important events is: - [eCos CDL](http://ecos.sourceware.org/docs-1.3.1/cdl/language.html) - was the inspiration for a component based design (early 2000s) -- in 2013, the **GNU ARM Eclipse plug-ins** (later rebranded as the + was the inspiration for a component based design (early 2000s). +- In 2013, the **GNU ARM Eclipse plug-ins** (later rebranded as the [Eclipse Embedded CDT](https://eclipse-embed-cdt.github.io)) was the first attempt to find a solution that avoids generating **make** - files by hand, but this prevented building and running unit tests in - a scriptable environment -- in 2013, the experimental [XCDL](http://xcdl.github.io) + files by hand, but this prevented the building and running of unit tests in + a scriptable environment. +- In 2013, the experimental [XCDL](http://xcdl.github.io) (eXtended Components Definition Language) project, inspired by - eCos CDL, implemented in Python, validated the concept + eCos CDL, implemented in Python, validated the concept. :::note - The major weakness of XCDL was the + The major weakness of this XCDL implementation was the limitation introduced by having the build configuration metadata as a Python code: **it could be edited only manually**, and not via a GUI based IDE (compared, for example, to the C/C++ settings in Eclipse CDT, which writes back the XML configuration file)". ::: -- in 2014, the **CMSIS Packs** solution was evaluated, and an +- In 2014, the **CMSIS Packs** solution was evaluated, and an Eclipse plug-in was - created to manage them, but the solution was later found to have - too many design issues, and was abandoned -- in 2015, the [yotta](https://github.com/ARMmbed/yotta) solution was - considered, and the first XCDL packs based on yotta were tested; - for various reasons, **yotta** was later abandoned by Arm + created to manage them. However the solution was later found to have + too many design issues, and was abandoned. +- In 2015, the [yotta](https://github.com/ARMmbed/yotta) solution was + considered, and the first XCDL packs based on yotta were tested. + For various reasons, **yotta** was later abandoned by Arm. :::note As yotta was strongly influenced by **npm**, the npm ecosystem was considered a good starting point for a future solution. ::: -- in 2017, the first release of **xpm** was available, as a complementary +- In 2017, the first release of **xpm** was made available as a complementary solution to **npm**, and packages managed by it were named **xPacks**; **xpm** complements [npm](https://en.wikipedia.org/wiki/Npm_(software)) as the industry standard package manager for JavaScript packages, and uses the same [npmjs.com](https://www.npmjs.com) as the hugely popular public - package repository -- in 2019, **xpm** was extended to also support + package repository. +- In 2019, **xpm** was extended to also support installing binary packages, and a new class of tools was created as - [xPack Binary Development Tools](https://github.com/xpack-dev-tools/) -- in 2022, **xpm** was used to build the binary packages; this proved that + [xPack Binary Development Tools](https://github.com/xpack-dev-tools/). +- In 2022, **xpm** was used to build the binary packages, proving that **the technology is standalone**, with the newer versions of the tools - being built with existing xPacks -- in 2023, with most of the tools in place, a first C/C++ project + being built with existing xPacks. +- In 2023, with most of the tools in place, a first C/C++ project ([@micro-os-plus/utils-lists](https://github.com/micro-os-plus/utils-lists-xpack/)) - was fully tested via **xpm**, validating again the whole concept + was fully tested via **xpm**, once again validating the whole concept. ## The xPack project goals -The project came to life as a practical need to find a replacement for the -Eclipse CDT managed build, with the additional requirement -to be able to run unit tests in a scriptable environment. +The project came to life out of a practical need to find a replacement +for the Eclipse CDT managed build, with the additional requirement of +being able to run unit tests in a scriptable environment. :::note -In the beginning it looked easy, -but later it proved to be quite a challenge, -and required defining sub-goals and achieving them in sequence. +In the beginning, it seemed easy, but it later proved to be quite a +challenge and required defining sub-goals and achieving them in sequence. ::: -By trial and error, the main aspects that need to be -addressed by such a solution were identified as: +Through trial and error, the main aspects that need to be addressed by +such a solution were identified as: -- the **build** (defining which files enter the build, the compiler/linker - options, etc) -- the **application configuration** (e.g. managing the values of the #define - in a consistent way) -- the **tools** (toolchains, debuggers, emulators, etc) +- The **build** (defining which files enter the build, the compiler/linker + options, etc). +- The **application configuration** (e.g. managing the values of the #define + in a consistent way). +- The **tools** (toolchains, debuggers, emulators, etc). ## The XCDL experimental version The first experimental solution was [XCDL](http://xcdl.github.io), -which was used in the **µOS++ Second Edition**; -basically some of the +which was used in the **µOS++ Second Edition**. +Essentially, some of the [eCos CDL](http://ecos.sourceware.org/docs-1.3.1/cdl/language.html) functionality was implemented in Python. @@ -114,151 +113,145 @@ The implementation was quite easy, and worked pretty well. However several issues were identified: -- using configuration files written in a programming language was +- Using configuration files written in a programming language was convenient, but it had a major drawback: since parsing Python is not trivial, it prevented the configuration - being edited with a GUI tool (similar to the Eclipse settings pages); - in other words, **the configuration - files must be in a structured format**, otherwise editing them by a - machine is problematic -- although the µOS++ SE was more or less modular, the project was - basically a **mono-repo**, and **writing unit tests for each module was - difficult** -- running unit tests with several toolchains, not to - mention with different versions of the same toolchain, proved - extremely difficult, and doing this on multiple platforms - (macOS, Windows, GNU/Linux) was even more difficult + being edited with a GUI tool (similar to the Eclipse settings pages). + In other words, **the configuration + files must be in a structured format**; otherwise editing them by a + machine is problematic. +- Although the µOS++ SE was more or less modular, the project was + basically a **mono-repo**, making it **difficult to write unit tests + for each module**. +- Running unit tests with several toolchains, not to + mention different versions of the same toolchain, proved + extremely difficult. Doing this on multiple platforms + (macOS, Windows, GNU/Linux) was even more challenging. The lessons learned from this experiment were: -- if a configuration needs to be edited by a machine, - it must be written in a **structured format**, - **JSON** being the favourite -- if each module is expected to be tested, it is better - to use **multiple small repositories**, each with its CI tests -- if the project is split into multiple packages, a tool to automate - installing/managing the **dependencies** is a great addition -- toolchains and other tools need to be **standalone & relocatable**, - to allow multiple versions to be installed in different folders - on the same machine; managing these multiple tools can also be - automated with a tool +- If a configuration needs to be edited by a machine, + it must be written in a **structured format**, with + **JSON** being the preferred choice. +- If each module is expected to be tested, it is better + to use **multiple small repositories**, each with its CI tests. +- If the project is split into multiple packages, a tool to automate + the installation and management of dependencies is a great addition. +- Toolchains and other tools need to be **standalone and relocatable**, + allowing multiple versions to be installed in different folders on + the same machine. Managing these multiple tools can also be automated + with a tool. -## Binary xPacks +## Binary xpm packages The first binary tools prepared were **arm-none-eabi-gcc**, **openocd**, -**qemu** and **windows-build-tools**; they were also used in Eclipse project; -initially they were installed manually, and Eclipse was able to +**qemu** and **windows-build-tools**. They were also used in Eclipse project. +Initially, they were installed manually, and Eclipse was able to identify them in certain fixed location. ## npm/xpm -While searching for a solution to automate installing different -source packages, a solution that looked pretty close to the needs -was **npm**. +While searching for a solution to automate the installation of different +source packages, **npm** appeared to be a close fit. -However, using **npm** directly proved not a fortunate solution, since -the **npm** strategy to install dependencies is specific to JavaScript, with -hierarchical packages. +However, using **npm** directly proved to be an unfortunate solution, +as **npm**'s strategy for installing dependencies is specific to +JavaScript, with hierarchical packages. -Therefore, it was decided that a new tool is needed, mainly -to handle the C/C++ linear dependencies; -this is how **xpm** was created. -Although it preserves the general look and feel and the design concepts -of **npm**, it is not a replacement of **npm**. +Therefore, it was decided that a new tool was needed, primarily to +handle the linear dependencies of C/C++. This is how **xpm** was +created. Although it preserves the general look and feel and design +concepts of **npm**, it is not a replacement for **npm**. -Later **xpm** was extended to automate installing the toolchains and -other binary archives. -As of now, there are toolchains for Arm, AArch64, RISC-V and native -(GCC & clang), that run on Windows, Linux, macOS; it is probably fair -to say that -the tools part of the project is covered properly, and fully automated. +Later, **xpm** was extended to automate the installation of +toolchains and other binary archives. + +As of now, there are toolchains for Arm, AArch64, RISC-V, and +native (GCC & clang) that run on Windows, Linux, and macOS. +It is probably fair to say that the tools part of the project is +properly covered and fully automated. ## Build system generators -As for the build and configuration tools in the project, things are -work in progress. - -For the build, the first idea was to rewrite the initial -Python code in JavaScript, but later a step by step approach -was considered. - -In the first step the existing build system generators were used, -like **CMake** and **meson**, with several advantages: - -- they allow to add tests to the µOS++ projects immediately, - without having to wait for any special/future tools -- they are a good chance to get a lot of experience on how to organise - projects with such tools -- they provide the users a direct way to integrate the µOS++ - source code libraries - into their existing projects built with CMake/meson. - -To manage the multi-platform, multi-architecture, multi-version, -multi-etc tests, a tool to manage **multiple build configurations** -was needed, -and since each configuration needs its own tools, with different -versions, it became clear that the build configurations must be -managed by the same tool, so **xpm** was extended to handle multiple -**build configurations**; later, **xPack actions** were added, to automate -running sequences of commands, like cmake or meson, to build -and run the tests. +As for the build and configuration tools in the project, work +is still in progress. + +For the build, the initial idea was to rewrite the Python code +in JavaScript, but a step-by-step approach was later considered. + +In the first step, existing build system generators like **CMake** +and **meson** were used, offering several advantages: + + +- They allow tests to be added to the µOS++ projects immediately, + without waiting for any special or future tools. +- They provide a valuable opportunity to gain experience in + organising projects with such tools. +- They offer users a direct way to integrate the µOS++ source + code libraries into their existing projects built with CMake + or Meson. + +To manage the multi-platform, multi-architecture, multi-version, and +other varied tests, a tool to manage **multiple build configurations** +was needed. Since each configuration requires its own tools, with +different versions, it became clear that the build configurations +must be managed by the same tool. Therefore, **xpm** was extended +to handle multiple **build configurations**. Later, **xpm actions** +were added to automate running sequences of commands, such as CMake +or meson, to build and run the tests. ## Future plans ### µOS++ -At the moment of writing this (mid 2023), the project is pretty advanced, -but it is not yet complete. +As of mid-2023, the project is quite advanced, but it is not yet complete. -In the future (2025) it is planned that all the +In the future (2025), it is planned that all the [µOS++ projects](https://github.com/micro-os-plus) to be updated to use -the multiple build configurations automated by **xpm**, and so -have everything fully tested in µOS++. +the multiple build configurations automated by **xpm**, +ensuring everything is fully tested in µOS++. -With the experience from this step, the next step is to finalise the -specs for the **xPack Project Builder** that will perform the -builds and manage the project configurations. +With the experience gained from this step, the next step is to finalise the +specifications for the xPack CDL, which will handle the configuration and +build processes. -The tool will probably be called **xpmake**, +The tool will probably be called **xcdl**, and will use json files, with a content similar to this one: -- [xpack.json](https://github.com/micro-os-plus/utils-lists-xpack/blob/xpack/xpack.json) +- [xcdl.json](https://github.com/micro-os-plus/utils-lists-xpack/blob/xpack-development/xcdl.json) As it can be seen, this file defines the **include folders**, the **source files**, and some **preprocessor definitions** that might be enabled while building the project. -This file, together with all other similar files from the packages -that are part of the project, will provide the input data for a tree -of **components**, that can be rendered in a graphical tool like **VS Code**, -thus allowing to configure a project in a way similar, -possibly even more advanced, than -the **Eclipse CDT** settings, since the hierarchical components reflect -the logical structure of the application, and allow to automatically -manage dependencies between components, and between configuration -options. +This file, along with all other similar files from the packages that +are part of the project, will provide the input data for a tree of +**components** that can be rendered in a graphical tool like VS Code. +This allows for project configuration in a manner similar to, or +possibly even more advanced than, the **Eclipse CDT** settings. +The hierarchical components reflect the logical structure of the +application and enable the automatic management of dependencies +between components and configuration options. ### Visual Studio Code -Additions to the **VS Code xPack extension** are planned, -to edit the tree of xPack CDL components, and run -the builds directly, without CMake/meson; this will -be a true xPack enabled tool, and will be an alternate solution to -Eclipse Embedded CDT. +Additions to the **VS Code xPack extension** are planned with features +to edit the tree of xPack CDL components and run the builds directly, +without CMake/meson. This will be a true xPack-enabled tool and an +alternative solution to Eclipse Embedded CDT. -But the use of this tool should be **optional**, the whole functionality -should also be -available from a terminal and a plain text editor. +However, the use of this tool should be **optional**. The entire +functionality should also be available from a terminal and a +plain text editor. ## Conclusions -As it can be seen, the xPack project originated from **the need to automate -the workflow for existing open source projects**, -especially the execution of multiple tests for embedded -projects, which often poses more challenges than developing -the projects themselves. +As can be seen, the xPack project originated from **the need to +automate the workflow for existing open-source projects**, particularly +the execution of multiple tests for embedded projects, which often poses +more challenges than developing the projects themselves. ## To be continued... diff --git a/website/sidebar-docs-custom.ts b/website/sidebar-docs-custom.ts index dccbd59..c476236 100644 --- a/website/sidebar-docs-custom.ts +++ b/website/sidebar-docs-custom.ts @@ -19,58 +19,27 @@ export const customDocsSidebar = [ }, collapsed: false, items: [ - { - type: 'doc', - id: 'getting-started/prerequisites/index', - label: 'Prerequisites' - }, { type: 'doc', id: 'getting-started/glossary/index', label: 'Glossary' }, - ] - }, - { - type: 'doc', - id: 'support/index', - label: 'Help Centre' - }, - { - type: 'category', - label: 'Project', - link: { - type: 'doc', - id: 'project/about/index', - }, - collapsed: false, - items: [ - { - type: 'doc', - id: 'project/about/index', - label: 'About' - }, { type: 'doc', - id: 'project/history/index', - label: 'History' + id: 'getting-started/prerequisites/index', + label: 'Prerequisites' }, ] }, { type: 'category', - label: 'Developer Information', + label: 'Contributor\'s Guide', link: { type: 'doc', id: 'developer/index', }, collapsed: true, items: [ - { - type: 'doc', - id: 'developer/new-xpack-git/index', - label: 'How to create new projects' - }, { type: 'doc', id: 'developer/js-style-guide/index', @@ -96,6 +65,32 @@ export const customDocsSidebar = [ { type: 'doc', id: 'maintainer/index', - label: 'Maintainer Information' + label: 'Maintainer\‘s Guide' + }, + { + type: 'doc', + id: 'support/index', + label: 'Help Centre' + }, + { + type: 'category', + label: 'Project', + link: { + type: 'doc', + id: 'project/about/index', + }, + collapsed: false, + items: [ + { + type: 'doc', + id: 'project/about/index', + label: 'About' + }, + { + type: 'doc', + id: 'project/history/index', + label: 'History' + }, + ] }, ]