Skip to content

Commit

Permalink
website update
Browse files Browse the repository at this point in the history
  • Loading branch information
@ilg-ul
ilg-ul committed Dec 9, 2024
1 parent 08126f9 commit 68036c7
Show file tree
Hide file tree
Showing 4 changed files with 226 additions and 195 deletions.
75 changes: 41 additions & 34 deletions website/docs/cli/xpm/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,12 @@ date: 2017-10-09 12:50:00 +0300

---

import CodeBlock from '@theme/CodeBlock';

import customField from '@site/src/libs/customField';

{/* ------------------------------------------------------------------------ */}

# xpm

## Synopsis
Expand All @@ -21,8 +27,9 @@ xpm <command> [<subcommand>...] [<options> ...] [<args>...]

## Description

`xpm` is the xPacks project manager. It manages dependencies
and puts packages in known places so that builds can find them.
`xpm` is the xPacks project manager. It handles dependencies and
places packages in designated locations, ensuring that builds can
locate them efficiently.

:::info

Expand All @@ -32,23 +39,24 @@ uses the same public registry at https://registry.npmjs.org."

:::

The program accepts a command name, possibly one or more subcommand
names, options (that start with a dash) and possibly one or more
arguments, like names, files, etc.
The programme accepts a command name, potentially accompanied by one
or more subcommand names, options (which begin with a dash), and
possibly one or more arguments, such as names or files.

The list of accepted options and arguments is specific to a given
command, or set of command and subcommands.
command or set of commands and subcommands.

## Common options

### Help (`-h|--help`)

To get an initial glimpse on the program, ask for help:
To gain an initial understanding of the programme, request help:

```console
$ xpm --help

The xPack package manager command line tool
<CodeBlock language="console"> {
`% xpm --help
The xPack project manager command line tool
Usage: xpm <command> [<subcommand>...] [<options> ...] [<args>...]
where <command> is one of:
Expand All @@ -70,20 +78,20 @@ xpm <command> -h|--help Quick help on command
xpm --version Show version
xpm -i|--interactive Enter interactive mode
npm xpm@0.9.0 '/Users/ilg/.nvm/versions/node/v14.16.0/lib/node_modules/xpm'
Home page: <https://xpack.github.io/xpm/>
Bug reports: <https://github.com/xpack/xpm-js/issues/>
```
npm xpm@${customField('releaseVersion')} '/Users/ilg/.nvm/versions/node/v20.18.0/lib/node_modules/xpm'
Home page: <https://xpack.github.io/xpm-preview/>
Bug reports: <https://github.com/xpack/xpm-js/issues>
`} </CodeBlock>

This works both at top level and with commands/subcommands.
This functions both at top level and with commands/subcommands.

### Log level (`--loglevel`)

The default behaviour of the program is to display only a minimum
amount of messages.

This can be changed, from not displaying any messages at all (`--silent`)
to displaying lots of debugging trace messages (`--trace`).
This can be adjusted, ranging from not displaying any messages at all
(`--silent`) to displaying numerous debugging trace messages (`--trace`).

```console
--loglevel <level> Set log level (silent|warn|info|verbose|debug|trace)
Expand All @@ -97,27 +105,26 @@ to displaying lots of debugging trace messages (`--trace`).

### Current folder (`-C`)

By default the program is executed in the context of the current shell
folder, but it can be changed to any folder using `-C <folder>`.
By default, the program is executed within the context of the current shell
folder> However, this can be changed to any folder using `-C <folder>`.

### Program version (`--version`)

As for most command line tools, it is possible to ask for the current
version, with `--version`:
As with most command line tools, it is possible to request the current version, with `--version`:

```console
$ xpm --version
0.9.0
```
<CodeBlock language="console"> {
`% xpm --version
${customField('releaseVersion')}
`} </CodeBlock>

The result is written to the standard output stream, and consists of the
semver string, without any `v` prefix, so it can be directly used in
automated scripts, without any post processing.
The result is written to the standard output stream and consists of the
semver string, without any `v` prefix. This allows it to be directly
used in automated scripts without any post-processing.

### Skip checks (`--no-update-notifier`)

By default, before exiting, `xpm` checks, once a day, if there is a
new version of the program available.
By default, before exiting, `xpm` checks once a day if a new version
of the programme is available.

For environments where this check is not necessary, it can be disabled.

Expand All @@ -128,13 +135,13 @@ The common use case is to start the program for each single command.
It is also possible to start the program with a prompt, and issue as many
commands as needed.

```console
$ xpm -i
<CodeBlock language="console"> {
`% xpm -i
xpm> version
0.9.0
${customField('releaseVersion')}
xpm>
...
```
`} </CodeBlock>

## Commands

Expand Down
173 changes: 78 additions & 95 deletions website/docs/cli/xpm/init/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,17 @@ keywords:
- xpm
- cli
- init

date: 2017-10-09 12:55:00 +0300

---

import CodeBlock from '@theme/CodeBlock';

import customField from '@site/src/libs/customField';

{/* ------------------------------------------------------------------------ */}

# xpm init

## Synopsis
Expand All @@ -27,17 +33,17 @@ Aliases:

## Description

Initialise the current folder as an xpm package, by creating a skeleton
`package.json` file. This file needs further editing to update most
Initialise the current folder as an xpm package by creating a skeleton
`package.json` file. This file requires further editing to update most
of the objects.

If called with a template, use the template and create a custom
project with as many files and folders as necessary.
If invoked with a template, use the template to create a custom project
with as many files and folders as necessary.

:::info

The current behaviour may change,
the template API is not yet final.
as the template API is not yet final.

:::

Expand All @@ -46,17 +52,18 @@ the template API is not yet final.

### Help (`--help`)

```console
$ xpm init --help
<CodeBlock language="console"> {
`% xpm init --help
xPack manager - create an xPack, empty or from a template
xPack project manager - create an xpm package, empty or from a template
Usage: xpm init [options...] [--template <xpack>] [--name <string>]
[--property <string>]*
[--property <string>]* [--ignore-errors]
Init options:
-t|--template <xpack> The xPack implementing the template (optional)
-t|--template <xpack> The xpm package implementing the template (optional)
-n|--name <string> Project name (optional)
-p|--property <string> Substitution variables (optional, multiple)
--ignore-errors Ignore script errors (optional)
Common options:
--loglevel <level> Set log level (silent|warn|info|verbose|debug|trace)
Expand All @@ -69,67 +76,54 @@ Common options:
--no-update-notifier Skip check for a more recent version
-C <folder> Set current folder
xpm -h|--help Quick help
xpm --version Show version
xpm -i|--interactive Enter interactive mode
xpm -h|--help Quick help
xpm --version Show version
xpm -i|--interactive Enter interactive mode
npm [email protected] '/Users/ilg/.nvm/versions/node/v14.16.0/lib/node_modules/xpm'
Home page: <https://xpack.github.io/xpm/>
Bug reports: <https://github.com/xpack/xpm-js/issues/>
$
```
npm xpm@${customField('releaseVersion')} '/Users/ilg/.nvm/versions/node/v20.18.0/lib/node_modules/xpm'
Home page: <https://xpack.github.io/xpm-preview/>
Bug reports: <https://github.com/xpack/xpm-js/issues>
`} </CodeBlock>

### Template (`-t|--template <xpack>`)

Create the xpm package using a template. The template itself is an xpm package
with a specific code that implements a template API.
containing a specific code that implements the template API.

Example: Create a project in an interactive session by answering
lots of questions:
#### Example

Create a project in an interactive session by answering
several questions:

```console
$ xpm init --template @sifive/templates --verbose
xPack manager - create an xPack, empty or from a template

Processing @sifive/[email protected]...

Programming language? (c, cpp, ?) [cpp]:
Board? (hifive1, e31arty, e51arty, ?) [hifive1]:
Content? (empty, blinky, ?) [blinky]:
Use system calls? (none, retarget, semihosting, ?) [retarget]:
Trace output? (none, uart0ftdi, stdout, debug, ?) [uart0ftdi]:
Check some warnings? (true, false, ?) [true]:
Check most warnings? (true, false, ?) [false]:
Enable -Werror? (true, false, ?) [false]:
Use -Og on debug? (true, false, ?) [false]:
Use newlib nano? (true, false, ?) [true]:

Creating the C++ project 'hifive1-blinky-cpp'...
% mkdir my-project && cd my-project
% xpm init --template @xpack/hello-world-template@latest

Checking package @xpack/hello-world-template@latest metadata...
Processing @xpack/[email protected]...

Programming language? (c, cpp, ?) [cpp]: c
Build System? (cmake, meson, autotools, ?) [cmake]:
Toolchain? (gcc, clang, system, ?) [gcc]: clang
Creating the C project 'my-project'...
File 'include/hello-world.h' copied.
File 'src/hello-world.c' copied.
File 'libs/adder/include/add/add.h' copied.
File 'libs/adder/src/add.c' copied.
Folder 'cmake' copied.
File 'CMakeLists.txt' generated.
File '.vscode/tasks.json' copied.
File '.vscode/settings.json' copied.
File '.gitignore' copied.
File '.npmignore' copied.
File 'README.md' generated.
File 'LICENSE' generated.
File 'oocd.launch' generated.
File 'jlink.launch' generated.
File 'package.json' generated.
File 'README.md' generated.
File 'xmake.json' generated.
File 'include/led.h' generated.
File 'include/sysclock.h' copied.
File 'ldscripts/libs.ld' copied.
File 'ldscripts/mem.ld' copied.
File 'ldscripts/sections.ld' copied.
File 'src/initialize-hardware.cpp' generated.
File 'src/interrupts-handlers.cpp' generated.
File 'src/led.cpp' copied.
File 'src/main.cpp' generated.
File 'src/newlib-syscalls.c' copied.
File 'src/sysclock.cpp' copied.

'xpm init' completed in 77 ms.
$
```

### Name (`--name <string>`)

Define a name for the new xpm package. If missing, the package name is
Define a name for the new xpm package. If omitted, the package name is
derived from the current folder name.

### Properties (`-p|--property <string>`)
Expand All @@ -139,45 +133,34 @@ properties can be defined.

The names, values and behaviours are all specific to each template engine.

Example: the same template as before, if it receives a mandatory
`boardName` property,
can create the new xpm package without further questions, by using defaults:
#### Example

```console
$ xpm init --template @sifive/templates --property boardName=hifive1
xPack manager - create an xPack, empty or from a template

Processing @sifive/[email protected]...

Creating the C++ project 'hifive1-blinky-cpp'...
- boardName=hifive1
- content=blinky
- syscalls=retarget
- trace=uart0ftdi
- useSomeWarnings=true
- useMostWarnings=false
- useWerror=false
- useOg=false
- useNano=true
The same template as before, if it receives a mandatory
`language` property,
can create the new xpm package without further questions by using defaults:

```console
% mkdir -p my-project && cd my-project
% xpm init --template @xpack/hello-world-template@latest --property language=c --property toolchain=clang

Installing @xpack/[email protected]...
Processing @xpack/[email protected]...

Creating the C project 'my-project'...
- buildGenerator=cmake
- toolchain=clang

File 'include/hello-world.h' copied.
File 'src/hello-world.c' copied.
File 'libs/adder/include/add/add.h' copied.
File 'libs/adder/src/add.c' copied.
Folder 'cmake' copied.
File 'CMakeLists.txt' generated.
File '.vscode/tasks.json' copied.
File '.vscode/settings.json' copied.
File '.gitignore' copied.
File '.npmignore' copied.
File 'README.md' generated.
File 'LICENSE' generated.
File 'oocd.launch' generated.
File 'jlink.launch' generated.
File 'package.json' generated.
File 'README.md' generated.
File 'xmake.json' generated.
File 'include/led.h' generated.
File 'include/sysclock.h' copied.
File 'ldscripts/libs.ld' copied.
File 'ldscripts/mem.ld' copied.
File 'ldscripts/sections.ld' copied.
File 'src/initialize-hardware.cpp' generated.
File 'src/interrupts-handlers.cpp' generated.
File 'src/led.cpp' copied.
File 'src/main.cpp' generated.
File 'src/newlib-syscalls.c' copied.
File 'src/sysclock.cpp' copied.

'xpm init' completed in 1.144 sec.
$
```
Loading

0 comments on commit 68036c7

Please sign in to comment.