diff --git a/jsdoc.json b/jsdoc.json index ee0aac5f57..124be7ba83 100644 --- a/jsdoc.json +++ b/jsdoc.json @@ -3,7 +3,7 @@ "allowUnknownTags": false }, "source": { - "include": ["docs/indexJsdoc.md"], + "include": ["packages/documentation/docs/indexJsdoc.md"], "exclude": [ "node_modules/@ui5/builder/lib/lbt/utils/JSTokenizer.js", "node_modules/@ui5/builder/lib/processors/jsdoc/lib/ui5/plugin.js", diff --git a/docs/images/Module_overview.png b/packages/documentation/docs/images/Module_overview.png similarity index 100% rename from docs/images/Module_overview.png rename to packages/documentation/docs/images/Module_overview.png diff --git a/docs/images/UI5_CLI/Task_Minify.svg b/packages/documentation/docs/images/UI5_CLI/Task_Minify.svg similarity index 100% rename from docs/images/UI5_CLI/Task_Minify.svg rename to packages/documentation/docs/images/UI5_CLI/Task_Minify.svg diff --git a/docs/images/UI5_logo.png b/packages/documentation/docs/images/UI5_logo.png similarity index 100% rename from docs/images/UI5_logo.png rename to packages/documentation/docs/images/UI5_logo.png diff --git a/docs/images/UI5_logo_wide.png b/packages/documentation/docs/images/UI5_logo_wide.png similarity index 100% rename from docs/images/UI5_logo_wide.png rename to packages/documentation/docs/images/UI5_logo_wide.png diff --git a/docs/images/favicon.png b/packages/documentation/docs/images/favicon.png similarity index 100% rename from docs/images/favicon.png rename to packages/documentation/docs/images/favicon.png diff --git a/docs/images/logo.svg b/packages/documentation/docs/images/logo.svg similarity index 100% rename from docs/images/logo.svg rename to packages/documentation/docs/images/logo.svg diff --git a/docs/index.md b/packages/documentation/docs/index.md similarity index 100% rename from docs/index.md rename to packages/documentation/docs/index.md diff --git a/docs/indexJsdoc.md b/packages/documentation/docs/indexJsdoc.md similarity index 100% rename from docs/indexJsdoc.md rename to packages/documentation/docs/indexJsdoc.md diff --git a/docs/pages/Benchmarking.md b/packages/documentation/docs/pages/Benchmarking.md similarity index 100% rename from docs/pages/Benchmarking.md rename to packages/documentation/docs/pages/Benchmarking.md diff --git a/docs/pages/Builder.md b/packages/documentation/docs/pages/Builder.md similarity index 100% rename from docs/pages/Builder.md rename to packages/documentation/docs/pages/Builder.md diff --git a/packages/documentation/docs/pages/CLI.md b/packages/documentation/docs/pages/CLI.md new file mode 100644 index 0000000000..1ab4eef208 --- /dev/null +++ b/packages/documentation/docs/pages/CLI.md @@ -0,0 +1,393 @@ +# UI5 CLI +## Requirements +- [Node.js](https://nodejs.org/) version v20.11.0 and higher or v22.0.0 and higher (v21 is not supported) +- [npm](https://www.npmjs.com/) version v8.0.0 or higher + +## Installation + +Install the CLI using the npm package manager: + +```sh +npm install --global @ui5/cli + +# Verify installation +ui5 --help +``` + +## Usage/Syntax + +` + ui5 [options] +` + +The CLI automatically checks for updates using [update-notifier](https://github.com/yeoman/update-notifier). While this is skipped in CI environments, you might also opt-out manually by following the steps described [here](https://github.com/yeoman/update-notifier/blob/-/readme.md#user-settings). + +## Common options + +These options you can use with each command. + +| Option | Description | Details | +| --- | --- | --- | +| -h, --help | Show help | [boolean] | +| -v, --version | Show version number | [boolean] | +| -c, --config | Path to project configuration file in YAML format | [string] | +| --dependency-definition | Path to a YAML file containing the project's dependency tree. This option will disable resolution of node package dependencies. | [string] | +| --workspace-config | Path to workspace configuration file in YAML format | [string] | +| -w, --workspace | Name of the workspace configuration to use | [string] [default: "default"] | +| --loglevel, --log-level | Set the logging level | [string] [choices: "silent", "error", "warn", "info", "perf", "verbose", "silly"] [default: "info"] | +| --verbose | Enable verbose logging. | [boolean] [default: false] | +| --perf | Enable performance measurements and related logging. | [boolean] [default: false] | +| --silent | Disable all log output. | [boolean] [default: false] | + +## Examples + +Execute command using a static dependency tree instead of resolving node package dependencies +``` +ui5 --dependency-definition /path/to/projectDependencies.yaml +``` +Execute command using a project configuration from custom path +``` +ui5 --config /path/to/ui5.yaml +``` +Execute command using the 'dolphin' workspace of a ui5-workspace.yaml +``` +ui5 --workspace dolphin +``` +Execute command with the maximum log output +``` +ui5 --log-level silly +``` + +## Commands + +### ui5 add + +**Description** + +Add SAPUI5/OpenUI5 framework libraries to the project configuration. + +**Usage** + +` +ui5 add [--development] [--optional] +` + + +**Options** + +| Option | Description | Details | +| --- | --- | --- | +| -D, --development, --dev | Add as development dependency | [boolean] [default: false] | +| -O, --optional | Add as optional dependency | [boolean] [default: false] | + +**Positionals** + +| Positional | Description | Details | +| --- | --- | --- | +| framework-libraries | Framework library names | [array] [required] [default: []] | + +**Examples** + +Add the framework libraries sap.ui.core and sap.m as dependencies +``` +ui5 add sap.ui.core sap.m +``` +Add the framework library sap.ui.support as development dependency +``` +ui5 add -D sap.ui.support +``` +Add the framework library themelib_sap_fiori_3 as optional dependency +``` +ui5 add --optional themelib_sap_fiori_3 +``` +### ui5 build + +**Description** + +Build project in current directory + +**Usage** + +` +ui5 build +` + +**Child Commands** + +| Command | Description | +| --- | --- | +| ui5 build jsdoc | Build JSDoc resources | +| ui5 build preload | (default) Build project and create preload bundles | +| ui5 build self-contained | Build project and create self-contained bundle. Recommended to be used in conjunction with --include-all-dependencies | + +**Options** + +| Option | Description | Details | +| --- | --- | --- | +| -a, --include-all-dependencies, --all | Include all dependencies in the build result. This is equivalent to '--include-dependency "*"' | [boolean] [default: false] | +| --include-dependency | A list of dependencies to be included in the build result. You can use the asterisk '*' as an alias for including all dependencies in the build result. The listed dependencies cannot be overruled by dependencies defined in 'exclude-dependency'. The provided name must match with the dependency name shown in 'ui5 ls --flat' | [array] | +| --include-dependency-regexp | A list of regular expressions defining dependencies to be included in the build result. This list is prioritized like 'include-dependency'. | [array] | +| --include-dependency-tree | A list of dependencies to be included in the build result. Transitive dependencies are implicitly included and do not need to be part of this list. These dependencies overrule the selection of 'exclude-dependency-tree' but can be overruled by 'exclude-dependency'. | [array] | +| --exclude-dependency | A list of dependencies to be excluded from the build result. The listed dependencies can be overruled by dependencies defined in 'include-dependency'. The provided name must match with the dependency name shown in 'ui5 ls --flat' | [array] | +| --exclude-dependency-regexp | A list of regular expressions defining dependencies to be excluded from the build result. This list is prioritized like 'exclude-dependency'. | [array] | +| --exclude-dependency-tree | A list of dependencies to be excluded from the build result. Transitive dependencies are implicitly included and do not need to be part of this list. | [array] | +| --dest | Path of build destination | [string] [default: "./dist"] | +| --clean-dest | If present, clean the destination directory before building | [boolean] [default: false] | +| --create-build-manifest | Store build metadata in a '.ui5' directory in the build destination, allowing reuse of the build result in other builds | [boolean] [default: false] | +| --include-task | A list of tasks to be added to the default execution set. This option takes precedence over any excludes. | [array] | +| --exclude-task | A list of tasks to be excluded from the default task execution set | [array] | +| --framework-version | Overrides the framework version defined by the project. Takes the same value as the version part of "ui5 use" | [string] | +| --cache-mode | Cache mode to use when consuming SNAPSHOT versions of framework dependencies. The 'Default' behavior is to invalidate the cache after 9 hours. 'Force' uses the cache only and does not create any requests. 'Off' invalidates any existing cache and updates from the repository | [string] [choices: "Default", "Force", "Off"] [default: "Default"] | +| --experimental-css-variables | Generate CSS variables (css-variables.css, css-variables.source.less) and skeleton (library-skeleton(-RTL).css) for all themes | [boolean] [default: false] | +| --output-style | Processes build results into a specific directory structure.
- Flat: Omits the project namespace and the "resources" directory.
- Namespace: Respects the project namespace and the "resources" directory, maintaining the original structure.
- Default: The default directory structure for every project type. For applications, this is identical to "Flat", and for libraries, it is "Namespace". Other types have a more distinct default output style. | [string] [choices: "Default", "Flat", "Namespace"] [default: "Default"] | + + +**Examples** + +Preload build for project without dependencies +``` +ui5 build +``` +Self-contained build for project +``` +ui5 build self-contained +``` +Build project but only apply the minify- and generateComponentPreload tasks +``` +ui5 build --exclude-task=* --include-task=minify generateComponentPreload +``` +Build project by applying all default tasks including the minify task and excluding the generateComponentPreload task +``` +ui5 build --include-task=minify --exclude-task=generateComponentPreload +``` +Preload build with experimental CSS variables artifacts +``` +ui5 build --experimental-css-variables +``` +### ui5 config + +**Description** + +Get and set UI5 CLI configuration options + +**Usage** + +` +ui5 config +` + +**Child Commands** + +| Command | Description | +| --- | --- | +| ui5 config set