diff --git a/.eslintrc.cjs b/.eslintrc.cjs index df2aa5b6928..e77c280b396 100644 --- a/.eslintrc.cjs +++ b/.eslintrc.cjs @@ -4,7 +4,7 @@ module.exports = { }, "env": { "node": true, - "es2022": true + "es2023": true }, "extends": ["eslint:recommended", "google"], "plugins": [], diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md index 53bc63746d0..6f92c37ac67 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -1,6 +1,6 @@ --- name: Bug Report -about: Report an issue with UI5 Tooling +about: Report an issue with UI5 CLI title: '' labels: bug, needs triage assignees: '' diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md index eae081cb38f..983b02869b5 100644 --- a/.github/ISSUE_TEMPLATE/feature-request.md +++ b/.github/ISSUE_TEMPLATE/feature-request.md @@ -1,6 +1,6 @@ --- name: Feature Request -about: Request a new feature to be added to UI5 Tooling +about: Request a new feature to be added to UI5 CLI title: '' labels: enhancement assignees: '' diff --git a/.github/dependabot.yml b/.github/dependabot.yml deleted file mode 100644 index 46e95262781..00000000000 --- a/.github/dependabot.yml +++ /dev/null @@ -1,20 +0,0 @@ -version: 2 -updates: -- package-ecosystem: "github-actions" - directory: "/" - schedule: - interval: "weekly" -- package-ecosystem: npm - directory: "/" - schedule: - interval: weekly - day: sunday - time: "10:00" - timezone: Etc/UCT - reviewers: - - RandomByte - - matz3 - versioning-strategy: increase - commit-message: - prefix: "[DEPENDENCY] " - prefix-development: "[INTERNAL] " diff --git a/.github/workflows/dependabot-auto-merge.yml b/.github/workflows/dependabot-auto-merge.yml index 31ea5d6b743..02c4e80e5b6 100644 --- a/.github/workflows/dependabot-auto-merge.yml +++ b/.github/workflows/dependabot-auto-merge.yml @@ -2,7 +2,7 @@ name: Dependabot auto-merge on: pull_request: branches: - - main + - v3 permissions: contents: write diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 512c2cd87a9..7e40e519f14 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -2,14 +2,17 @@ name: Build and Deploy Docs on: push: branches: - - main + - v3 + +permissions: + contents: write + jobs: build-and-deploy: name: Build and Deploy runs-on: ubuntu-latest env: MIKE_VERSION: v3 - MIKE_ALIAS: next DOCKER_IMAGE: ui5-tooling/mkdocs-material GIT_COMMITTER_NAME: "OpenUI5 Bot" GIT_COMMITTER_EMAIL: "openui5@sap.com" @@ -40,11 +43,6 @@ jobs: - name: Publish docs run: docker run --rm -v $(pwd):/docs --entrypoint mike --env GIT_COMMITTER_NAME="${GIT_COMMITTER_NAME}" --env GIT_COMMITTER_EMAIL="${GIT_COMMITTER_EMAIL}" $DOCKER_IMAGE set-default stable --push - - name: Build Schema - run: | - npm run schema-generate - npm run schema-workspace-generate - - name: Checkout gh-pages uses: actions/checkout@v4 with: @@ -52,11 +50,8 @@ jobs: path: gh-pages - name: Copy the additional resources to gh-pages run: | - rm -rf ./gh-pages/schema - cp -R ./site/schema ./gh-pages/ rm -rf ./gh-pages/$MIKE_VERSION/api cp -R ./site/api ./gh-pages/$MIKE_VERSION/ - cp ./scripts/resources/custom404.html ./gh-pages/404.html - name: Publish Docs run: | cd ./gh-pages diff --git a/.github/workflows/github-ci.yml b/.github/workflows/github-ci.yml index 95d8f475cc3..da8de293882 100644 --- a/.github/workflows/github-ci.yml +++ b/.github/workflows/github-ci.yml @@ -3,10 +3,10 @@ name: GitHub CI on: push: branches: - - main + - v3 pull_request: branches: - - main + - v3 jobs: test: diff --git a/.github/workflows/reuse-compliance.yml b/.github/workflows/reuse-compliance.yml index 2656d795c1b..64183233e7e 100644 --- a/.github/workflows/reuse-compliance.yml +++ b/.github/workflows/reuse-compliance.yml @@ -3,10 +3,10 @@ name: REUSE on: push: branches: - - main + - v3 pull_request: branches: - - main + - v3 jobs: compliance-check: diff --git a/.github/workflows/security-audit.yml b/.github/workflows/security-audit.yml deleted file mode 100644 index 25aaaf163ce..00000000000 --- a/.github/workflows/security-audit.yml +++ /dev/null @@ -1,25 +0,0 @@ -name: Security Audit - -on: - schedule: - - cron: "36 4 * * *" # Run once a day - workflow_dispatch: -jobs: - security-scan: - name: Security Audit - runs-on: ubuntu-latest - strategy: - matrix: - branch: ["v2"] # List of branches to run the security audit uppon - - steps: - - name: Checkout '${{ matrix.branch }}' branch - uses: actions/checkout@v4 - with: - ref: ${{ matrix.branch }} - - - name: install dependencies - run: npm ci - - - name: Use audit-ci - run: npx audit-ci@^6 --config ./audit-ci.jsonc diff --git a/.npmrc b/.npmrc index 93ec4f76ba6..3eeeab4e326 100644 --- a/.npmrc +++ b/.npmrc @@ -1,3 +1,4 @@ # Enforce public npm registry registry=https://registry.npmjs.org/ lockfile-version=3 +ignore-scripts=true diff --git a/.reuse/dep5 b/.reuse/dep5 index 4c008771945..e9d4a0d72c8 100644 --- a/.reuse/dep5 +++ b/.reuse/dep5 @@ -25,5 +25,5 @@ Disclaimer: The code in this project may include calls to APIs (β€œAPI Calls”) parties the right to use of access any SAP External Product, through API Calls. Files: * -Copyright: 2018-2024 SAP SE or an SAP affiliate company and UI5 Tooling contributors +Copyright: 2018-2024 SAP SE or an SAP affiliate company and UI5 CLI contributors License: Apache-2.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6fe44ebb27d..a0103ab6fa8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to the UI5 Tooling +# Contributing to the UI5 CLI ## Content 1. [πŸ“ **Reporting Issues**](#-reporting-issues) 2. [🀩 **Feature Requests**](#-feature-requests) @@ -11,12 +11,12 @@ ## πŸ“ Reporting Issues ### Seeking Help / Not a Bug -If you need help setting something up, or if you have questions regarding UI5 Tooling, please seek help on a community platform like the [SAP Community](https://answers.sap.com/topics/ui5-tooling.html), [StackOverflow](http://stackoverflow.com/questions/tagged/ui5-tooling) or the [`#tooling`](https://openui5.slack.com/archives/C0A7QFN6B) channel of the [OpenUI5 Community Slack](https://ui5-slack-invite.cfapps.eu10.hana.ondemand.com). +If you need help setting something up, or if you have questions regarding UI5 CLI, please seek help on a community platform like the [SAP Community](https://answers.sap.com/topics/ui5-tooling.html), [StackOverflow](http://stackoverflow.com/questions/tagged/ui5-tooling) or the [`#tooling`](https://openui5.slack.com/archives/C0A7QFN6B) channel of the [OpenUI5 Community Slack](https://ui5-slack-invite.cfapps.eu10.hana.ondemand.com). ### How to Report an Issue -Note that we collect issues for all UI5 Tooling modules (*[ui5-cli](https://github.com/SAP/ui5-cli), [ui5-server](https://github.com/SAP/ui5-server), [ui5-project](https://github.com/SAP/ui5-project), [ui5-builder](https://github.com/SAP/ui5-builder), [ui5-fs](https://github.com/SAP/ui5-fs) and [ui5-logger](https://github.com/SAP/ui5-logger)*) in the central [ui5-tooling](https://github.com/SAP/ui5-tooling) repository. +Note that we collect issues for all UI5 CLI modules (*[ui5-cli](https://github.com/SAP/ui5-cli), [ui5-server](https://github.com/SAP/ui5-server), [ui5-project](https://github.com/SAP/ui5-project), [ui5-builder](https://github.com/SAP/ui5-builder), [ui5-fs](https://github.com/SAP/ui5-fs) and [ui5-logger](https://github.com/SAP/ui5-logger)*) in the central [ui5-tooling](https://github.com/SAP/ui5-tooling) repository. -1. **Only UI5 Tooling issues** +1. **Only UI5 CLI issues** * Please do not report: * Issues caused by dependencies or plugins. * Issues caused by the use of non-public/internal methods. Only the public methods listed in the API documentation may be used. @@ -67,14 +67,14 @@ GitHub offers labels to categorize issues. The labels can only be set and modifi * **`wontfix`**: While acknowledged to be an issue, a fix cannot or will not be provided. ### Issue Reporting Disclaimer -We want to improve the quality of the UI5 Tooling and good bug reports are welcome! But our capacity is limited, so we cannot handle questions or consultation requests, and we cannot afford to ask for required details. +We want to improve the quality of the UI5 CLI and good bug reports are welcome! But our capacity is limited, so we cannot handle questions or consultation requests, and we cannot afford to ask for required details. -Therefore, we reserve the right to close or to not process insufficient bug reports in favor of those which are clearly documented and easy to reproduce. Even though we would like to solve each well-documented issue, there is always the chance that it won't happen - please remember: The UI5 Tooling is Open Source and comes without warranty. +Therefore, we reserve the right to close or to not process insufficient bug reports in favor of those which are clearly documented and easy to reproduce. Even though we would like to solve each well-documented issue, there is always the chance that it won't happen - please remember: The UI5 CLI is Open Source and comes without warranty. Bug report analysis support is always very welcome! See [Analyze Issues](#-analyzing-issues). ## 🀩 Feature Requests -You can request most features by creating an issue in the UI5 Tooling repository: https://github.com/SAP/ui5-tooling/issues/new +You can request most features by creating an issue in the UI5 CLI repository: https://github.com/SAP/ui5-tooling/issues/new For bigger features an RFC (Request for Comment) might be necessary. You should always clarify the need for an RFC with the project contributors upfront. You could do this either by opening an issue or in our [Slack channel](#seeking-help--not-a-bug). You can use [this template](rfcs/0000-template.md) for creating an RFC. @@ -88,13 +88,13 @@ You may be able to add additional or missing information, such as a step-by-step ## πŸ’» Contributing Code ### General Remarks -You are welcome to contribute code to the UI5 Tooling in order to fix bugs or to implement new features. +You are welcome to contribute code to the UI5 CLI in order to fix bugs or to implement new features. There are three important things to know: 1. You must be aware of the Apache License (which describes contributions) and **agree to the Developer Certificate of Origin***. This is common practice in major Open Source projects. To make this process as simple as possible, we are using *[CLA assistant](https://cla-assistant.io/)* for individual contributions. CLA assistant is an open source tool that integrates with GitHub very well and enables a one-click experience for accepting the DCO. For company contributers, special rules apply. See the respective section below for details. 2. Follow our **[Development Conventions and Guidelines](docs/Guidelines.md)**. -3. **Not all proposed contributions can be accepted**. Some features may just fit a third-party add-on better. The code must match the overall direction of the UI5 Tooling and improve it. So there should be some "bang for the byte". For most bug fixes this is a given, but a major feature implementation first needs to be discussed with one of the committers. Possibly, one who touched the related code or module recently. The more effort you invest, the better you should clarify in advance whether the contribution will match the project's direction. The best way would be to just open an enhancement ticket in the issue tracker to discuss the feature you plan to implement (make it clear that you intend to contribute). We will then forward the proposal to the respective code owner. This avoids disappointment. +3. **Not all proposed contributions can be accepted**. Some features may just fit a third-party add-on better. The code must match the overall direction of the UI5 CLI and improve it. So there should be some "bang for the byte". For most bug fixes this is a given, but a major feature implementation first needs to be discussed with one of the committers. Possibly, one who touched the related code or module recently. The more effort you invest, the better you should clarify in advance whether the contribution will match the project's direction. The best way would be to just open an enhancement ticket in the issue tracker to discuss the feature you plan to implement (make it clear that you intend to contribute). We will then forward the proposal to the respective code owner. This avoids disappointment. ### Developer Certificate of Origin (DCO) @@ -105,7 +105,7 @@ This DCO replaces the previously used CLA ("Contributor License Agreement") as w ### How to Contribute 1. Make sure the change is welcome (see [General Remarks](#general-remarks)). - - Also check on the [UI5 Tooling Task Board](https://github.com/orgs/SAP/projects/1) whether related tasks are already being worked on, blocked, or in discussion. + - Also check on the [UI5 CLI Task Board](https://github.com/orgs/SAP/projects/1) whether related tasks are already being worked on, blocked, or in discussion. 1. Create a branch by forking the relevant module repository and apply your change. 1. Commit and push your change on that branch. - πŸ‘‰ **Please follow our [Development Conventions and Guidelines](docs/Guidelines.md).** diff --git a/README.md b/README.md index c3d5e0c7ffd..261f2a1425b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ ![UI5 logo](./docs/images/UI5_logo_wide.png) -# UI5 Tooling +# UI5 CLI > An open and modular toolchain to develop state-of-the-art applications based on the [UI5](https://ui5.sap.com) framework. [![REUSE status](https://api.reuse.software/badge/github.com/SAP/ui5-tooling)](https://api.reuse.software/info/github.com/SAP/ui5-tooling) @@ -8,11 +8,8 @@ [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md) -> [UI5 Tooling v3](https://sap.github.io/ui5-tooling/v3) is the latest and stable version πŸŽ‰ -> -> [UI5 Tooling v2](https://sap.github.io/ui5-tooling/v2) has been deprecated 🚫 -> -> Please migrate your projects to [UI5 Tooling v3](https://sap.github.io/ui5-tooling/v3/updates/migrate-v3/)! +> ⚠️ UI5 CLI v3 has been deprecated! We highly recommend migrating to [**the latest version**](https://ui5.github.io/cli/stable/). + @@ -27,7 +24,7 @@ - [Roadmap](https://github.com/SAP/ui5-tooling/issues/701) ## Modules -UI5 Tooling consists of multiple modules. Each one is managed in a separate repository: +UI5 CLI consists of multiple modules. Each one is managed in a separate repository: - [ui5-cli](https://github.com/SAP/ui5-cli): UI5 Command Line Interface, utilizing all of the following modules - [ui5-project](https://github.com/SAP/ui5-project): Modules for building a UI5 project's dependency tree, including configuration diff --git a/SUPPORT.md b/SUPPORT.md index da5e7925769..16eac28b7db 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,6 +1,6 @@ ### Support -If you need help setting something up, or if you have questions regarding UI5 Tooling, please refrain from opening an issue on GitHub. +If you need help setting something up, or if you have questions regarding UI5 CLI, please refrain from opening an issue on GitHub. Instead, please use one of the following platforms to seek help: diff --git a/docs/images/UI5_Tooling/Task_Minify.svg b/docs/images/UI5_CLI/Task_Minify.svg similarity index 100% rename from docs/images/UI5_Tooling/Task_Minify.svg rename to docs/images/UI5_CLI/Task_Minify.svg diff --git a/docs/index.md b/docs/index.md index 9d9091a67bc..5bc3f7114e4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,9 +1,14 @@ ![UI5 logo](images/UI5_logo_wide.png) -# UI5 Tooling +# UI5 CLI An open and modular toolchain to develop state-of-the-art applications based on the [UI5](https://ui5.sap.com) framework. +!!! abstract "Project Rename" + **UI5 Tooling has been renamed to UI5 CLI 🚨** + + Read the announcement blog post: **[SAP Community: Goodbye UI5 Tooling - Hello UI5 CLI!](https://community.sap.com/t5/technology-blog-posts-by-sap/goodbye-ui5-tooling-hello-ui5-cli/ba-p/14211769)** + [**Get Started**](./pages/GettingStarted.md){: .md-button .md-button--primary .sap-icon-initiative } ## Main Features @@ -22,7 +27,7 @@ npm install --save-dev @ui5/cli #### βš™οΈ Project Setup -Configure your project for use with UI5 Tooling. +Configure your project for use with UI5 CLI. *Also see the [Configuration Documentation](./pages/Configuration.md)* ``` @@ -37,7 +42,7 @@ type: application #### 🚚 Dependency Management -UI5 framework dependencies are managed by the tooling. All other dependencies are managed by your favorite node package manager. +UI5 framework dependencies are managed by the UI5 CLI. All other dependencies are managed by your favorite node package manager. ``` ❯ ui5 use SAPUI5@1.117.0 @@ -84,10 +89,10 @@ info ProjectBuilder Executing cleanup tasks... ### πŸ§ͺ Node.js API -Most UI5 Tooling modules provide JavaScript APIs for direct consumption in other Node.js projects. -This allows you to rely on UI5 Tooling for UI5-specific build functionality and project handling, while creating your own tools to perfectly match the needs of your project. +Most UI5 CLI modules provide JavaScript APIs for direct consumption in other Node.js projects. +This allows you to rely on UI5 CLI for UI5-specific build functionality and project handling, while creating your own tools to perfectly match the needs of your project. -All available APIs are documented in the [UI5 Tooling API Reference](https://sap.github.io/ui5-tooling/v3/api/index.html). +All available APIs are documented in the [UI5 CLI API Reference](https://sap.github.io/ui5-tooling/v3/api/index.html). === "ESM" diff --git a/docs/indexJsdoc.md b/docs/indexJsdoc.md index f74412f9ef2..5fff6c5ae42 100644 --- a/docs/indexJsdoc.md +++ b/docs/indexJsdoc.md @@ -1,4 +1,4 @@ -# UI5 Tooling API Reference +# UI5 CLI API Reference ## Support Please follow our [Contribution Guidelines](https://github.com/SAP/ui5-tooling/blob/main/CONTRIBUTING.md#report-an-issue) on how to report an issue. Or chat with us in the [`#tooling`](https://openui5.slack.com/archives/C0A7QFN6B) channel of the [OpenUI5 Community Slack](https://ui5-slack-invite.cfapps.eu10.hana.ondemand.com) diff --git a/docs/pages/Benchmarking.md b/docs/pages/Benchmarking.md index 6befa5d9c5e..321ff98497f 100644 --- a/docs/pages/Benchmarking.md +++ b/docs/pages/Benchmarking.md @@ -1,6 +1,6 @@ -# Benchmarking UI5 Tooling +# Benchmarking UI5 CLI -For benchmarking UI5 Tooling we typically make use of the open source tool [hyperfine](https://github.com/sharkdp/hyperfine). +For benchmarking UI5 CLI we typically make use of the open source tool [hyperfine](https://github.com/sharkdp/hyperfine). In general we only benchmark calls to the UI5 CLI. However, we might add scripted benchmarks for some components in the future. @@ -9,10 +9,10 @@ The following is a walk-through on how to evaluate the performance impact of an ## Setup 1. Install [hyperfine](https://github.com/sharkdp/hyperfine#installation) -1. Prepare the UI5 Tooling projects you want to measure *(optional if your development environment already reflects this)*: +1. Prepare the UI5 CLI projects you want to measure *(optional if your development environment already reflects this)*: 1. Start in an empty directory ```sh - mkdir ui5-tooling-benchmark && cd ui5-tooling-benchmark/ + mkdir ui5-cli-benchmark && cd ui5-cli-benchmark/ ``` 1. Clone [UI5 CLI](https://github.com/SAP/ui5-cli) ```sh @@ -45,7 +45,7 @@ The following is a walk-through on how to evaluate the performance impact of an For example: ``` - 3.0.0 (from /my/home/ui5-tooling-benchmark/ui5-cli/bin/ui5.cjs) + 3.0.0 (from /my/home/ui5-cli-benchmark/ui5-cli/bin/ui5.cjs) ``` 1. Prepare your test project (we choose the [openui5-sample-app](https://github.com/SAP/openui5-sample-app)) @@ -64,11 +64,11 @@ The following is a walk-through on how to evaluate the performance impact of an Note: We won't link UI5 CLI into this project. Instead, we'll call it directly. 1. Verify that the previously installed UI5 CLI can be called with the following command: ```sh - UI5_CLI_NO_LOCAL=X node /my/home/ui5-tooling-benchmark/ui5-cli/bin/ui5.cjs --version + UI5_CLI_NO_LOCAL=X node /my/home/ui5-cli-benchmark/ui5-cli/bin/ui5.cjs --version ``` On Windows: ```sh - set UI5_CLI_NO_LOCAL=X node /my/home/ui5-tooling-benchmark/ui5-cli/bin/ui5.cjs --version + set UI5_CLI_NO_LOCAL=X node /my/home/ui5-cli-benchmark/ui5-cli/bin/ui5.cjs --version ``` *(Replace the path to ui5.cjs with the one shown in the previous `ui5 --version` output)* @@ -84,20 +84,20 @@ The following is a walk-through on how to evaluate the performance impact of an 1. In the project, start your first benchmark ```sh hyperfine --warmup 1 \ - 'UI5_CLI_NO_LOCAL=X node /my/home/ui5-tooling-benchmark/ui5-cli/bin/ui5.cjs build' \ + 'UI5_CLI_NO_LOCAL=X node /my/home/ui5-cli-benchmark/ui5-cli/bin/ui5.cjs build' \ --export-markdown ./baseline.md ``` On Windows: ```sh hyperfine --warmup 1 \ - 'set UI5_CLI_NO_LOCAL=X node /my/home/ui5-tooling-benchmark/ui5-cli/bin/ui5.cjs build' \ + 'set UI5_CLI_NO_LOCAL=X node /my/home/ui5-cli-benchmark/ui5-cli/bin/ui5.cjs build' \ --export-markdown ./baseline.md ``` 1. Your baseline benchmark is now stored in `baseline.md` and should look similar to this: | Command | Mean [s] | Min [s] | Max [s] | Relative | |:---|---:|---:|---:|---:| - | `UI5_CLI_NO_LOCAL=X node /my/home/ui5-tooling-benchmark/ui5-cli/bin/ui5.cjs build` | 1.439 Β± 0.036 | 1.400 | 1.507 | 1.00 | + | `UI5_CLI_NO_LOCAL=X node /my/home/ui5-cli-benchmark/ui5-cli/bin/ui5.cjs build` | 1.439 Β± 0.036 | 1.400 | 1.507 | 1.00 | 1. Prepare your change 1. Switch to the branch that contains your change @@ -108,19 +108,19 @@ The following is a walk-through on how to evaluate the performance impact of an ```sh (cd ../ui5-builder && npm install) ``` - 1. The link from UI5 CLI is still in place. However, if you have changes in **multiple** UI5 Tooling modules, you might need to `npm link` those again + 1. The link from UI5 CLI is still in place. However, if you have changes in **multiple** UI5 CLI modules, you might need to `npm link` those again 1. Perform the change measurement 1. In the project, start your second benchmark ```sh hyperfine --warmup 1 \ - 'UI5_CLI_NO_LOCAL=X node /my/home/ui5-tooling-benchmark/ui5-cli/bin/ui5.cjs build' \ + 'UI5_CLI_NO_LOCAL=X node /my/home/ui5-cli-benchmark/ui5-cli/bin/ui5.cjs build' \ --export-markdown ./my_change.md ``` On Windows: ```sh hyperfine --warmup 1 \ - 'set UI5_CLI_NO_LOCAL=X node /my/home/ui5-tooling-benchmark/ui5-cli/bin/ui5.cjs build' \ + 'set UI5_CLI_NO_LOCAL=X node /my/home/ui5-cli-benchmark/ui5-cli/bin/ui5.cjs build' \ --export-markdown ./my_change.md ``` 1. Your change's benchmark is now stored in `my_change.md` diff --git a/docs/pages/Builder.md b/docs/pages/Builder.md index 6e4f14413b5..a02cb32b65f 100644 --- a/docs/pages/Builder.md +++ b/docs/pages/Builder.md @@ -69,7 +69,7 @@ Related to this, the bundling tasks will also incorporate the generated source m For projects facilitating transpilation (such as TypeScript-based projects), it is commonly desired to debug in the browser using the original sources, e.g. TypeScript files. To make this work, the transpilation process first needs to create source maps and reference them in the generated JavaScript code. -UI5 Tooling's `minify` task will then find this reference and incorporate the source map into the minification process. In the end, the minified JavaScript resources will reference an updated source map, which reflects the transpilation as well as the minification. The browser can use this to map every statement back to the original TypeScript file, making debugging a breeze. +UI5 CLI's `minify` task will then find this reference and incorporate the source map into the minification process. In the end, the minified JavaScript resources will reference an updated source map, which reflects the transpilation as well as the minification. The browser can use this to map every statement back to the original TypeScript file, making debugging a breeze. !!! warning If a resource has been modified by another build task before `minify` is executed, any referenced source map will be ignored. This is to ensure the integrity of the source maps in the build result. @@ -81,7 +81,7 @@ UI5 Tooling's `minify` task will then find this reference and incorporate the so Expand the block below to view a diagram illustrating the minification process and source map handling. ??? info "Minification Activity Diagram" - ![minify Task Activity](../images/UI5_Tooling/Task_Minify.svg){ loading=lazy } + ![minify Task Activity](../images/UI5_CLI/Task_Minify.svg){ loading=lazy } ## Processors Processors work with provided resources. They contain the actual build step logic to apply specific modifications to supplied resources, or to make use of the resources' content to create new resources out of that. diff --git a/docs/pages/CodeAnalysis.md b/docs/pages/CodeAnalysis.md index 9ae875c383f..a80f402d9f5 100644 --- a/docs/pages/CodeAnalysis.md +++ b/docs/pages/CodeAnalysis.md @@ -1,6 +1,6 @@ # Code Analysis -During the build process, UI5 Tooling executes a static code analysis of your project. In the following sections the term "simple literal" is used for the following language features: +During the build process, UI5 CLI executes a static code analysis of your project. In the following sections the term "simple literal" is used for the following language features: - string literals - numeric literals @@ -12,7 +12,7 @@ During the build process, UI5 Tooling executes a static code analysis of your pr ## Dependency Analysis -UI5 Tooling extracts dependency information from a project's code as outlined in the following sections. +UI5 CLI extracts dependency information from a project's code as outlined in the following sections. The APIs described there require the usage of "simple literals" when declaring dependencies. ### JSModule Analyzer @@ -35,9 +35,9 @@ For example, top-level code is always executed. Flow-control statements in JavaS Any dependencies found that - according to these rules - are always executed, are collected as eager (or standard) dependencies. Dependencies that are found on a code path that depends on certain conditions are collected as conditional dependencies. -The bundling implemented by UI5 Tooling can either follow only eager dependencies (`resolve`: `true`) or additionally conditional dependencies (`resolveConditional`). For more information, see [Custom Bundling](https://sap.github.io/ui5-tooling/v3/pages/Configuration/#custom-bundling). +The bundling implemented by UI5 CLI can either follow only eager dependencies (`resolve`: `true`) or additionally conditional dependencies (`resolveConditional`). For more information, see [Custom Bundling](https://sap.github.io/ui5-tooling/v3/pages/Configuration/#custom-bundling). -When a dependency in one of the mentioned APIs is not a "simple literal" but an expression, the corresponding module is marked as "having dynamic dependencies". This marker is currently not further evaluated by the tooling. +When a dependency in one of the mentioned APIs is not a "simple literal" but an expression, the corresponding module is marked as "having dynamic dependencies". This marker is currently not further evaluated by UI5 CLI. ### Component Analyzer @@ -80,11 +80,11 @@ Additionally, some special dependencies are handled: - embedded fragments or views In an XMLView/XMLFragment, usually three categories of element nodes exist: Controls, aggregations, and non-UI5 nodes (e.g. XHTML or SVG). The third category usually can be identified by its namespace. To distinguish between the first two categories, the analyzer checks whether a resource exists in the project or its dependencies whose name matches the qualified node name. -For example, if the qualified node name is `sap.m.Text`, the analyzer checks whether `sap/m/Text.js` exists. If so, UI5 Tooling detects this node as a control, otherwise as an aggregation. +For example, if the qualified node name is `sap.m.Text`, the analyzer checks whether `sap/m/Text.js` exists. If so, UI5 CLI detects this node as a control, otherwise as an aggregation. ### XML Composite Analyzer -The **XMLComposite** control is deprecated since version UI5 1.88. Nevertheless, UI5 Tooling will attempt to analyze the declaration of any such controls in a project. +The **XMLComposite** control is deprecated since version UI5 1.88. Nevertheless, UI5 CLI will attempt to analyze the declaration of any such controls in a project. The [XML Composite Analyzer](https://github.com/SAP/ui5-builder/blob/main/lib/lbt/analyzer/XMLCompositeAnalyzer.js) searches for the name of the configured fragment containing the **XMLComposite** control. @@ -126,7 +126,7 @@ Note: Currently only the usage via the global `sap.ui.getCore().initLibrary` is ## JSDoc -The UI5 Tooling offers a JSDoc build, which is enhanced by UI5-specific JSDoc features. +The UI5 CLI offers a JSDoc build, which is enhanced by UI5-specific JSDoc features. An UI5 SDK can be built locally. To get more insight into the local UI5 SDK build setup, have a look at our [Developer's Guide](https://github.com/SAP/openui5/blob/master/docs/developing.md#building-the-openui5-sdk-demo-kit). @@ -135,11 +135,11 @@ Currently, the resources needed for a UI5 SDK build are stored in [openui5](http The following artefacts contribute to the JSDoc build: - [jsdocGenerator.js](https://github.com/SAP/ui5-builder/blob/main/lib/processors/jsdoc/jsdocGenerator.js): - Executes the actual JSDoc build. UI5 Tooling wrapper for `plugin.cjs`. + Executes the actual JSDoc build. UI5 CLI wrapper for `plugin.cjs`. - [sdkTransformer.js](https://github.com/SAP/ui5-builder/blob/main/lib/processors/jsdoc/sdkTransformer.js): - UI5 Tooling wrapper for `transformApiJson.cjs`. + UI5 CLI wrapper for `transformApiJson.cjs`. - [apiIndexGenerator.js](https://github.com/SAP/ui5-builder/blob/main/lib/processors/jsdoc/apiIndexGenerator.js): - UI5 Tooling wrapper for `createIndexFiles.cjs`. + UI5 CLI wrapper for `createIndexFiles.cjs`. - [createIndexFiles.cjs](https://github.com/SAP/ui5-builder/blob/main/lib/processors/jsdoc/lib/createIndexFiles.cjs): Creates API index resources from all `api.json` resources and by interpreting the `sap-ui-version.json` available in the given test resources directory. The resulting index resources (e.g. `api-index.json`, `api-index-deprecated.json`, `api-index-experimental.json` and `api-index-since.json`) are only to be used in a UI5 SDK. diff --git a/docs/pages/Configuration.md b/docs/pages/Configuration.md index c6fc04fbb4d..63e86e93c50 100644 --- a/docs/pages/Configuration.md +++ b/docs/pages/Configuration.md @@ -1,9 +1,9 @@ # Configuration -A projects UI5 Tooling configuration is typically located in a [YAML](https://yaml.org/) file named `ui5.yaml`, located in the root directory. +A projects UI5 CLI configuration is typically located in a [YAML](https://yaml.org/) file named `ui5.yaml`, located in the root directory. !!! info - This document describes the configuration of UI5 Tooling-based projects and extensions. It represents **[Specification Version 3.0](#specification-versions)**. + This document describes the configuration of UI5 CLI-based projects and extensions. It represents **[Specification Version 3.0](#specification-versions)**. ## Validation / IDE support @@ -83,7 +83,7 @@ This configuration defaults to `kind: project`, which means you typically only n A project must have a `name`. -In UI5 Tooling, a project is typically identified by the configured `name`. It must be unique and should ideally follow a namespace scheme like `organization.product.project` for UI5 projects or `ui5-task-heavy-boulder` for extension-projects. +In UI5 CLI, a project is typically identified by the configured `name`. It must be unique and should ideally follow a namespace scheme like `organization.product.project` for UI5 projects or `ui5-task-heavy-boulder` for extension-projects. The `name` property of **projects defining Specification Version 3.0 and higher** must satisfy the following conditions: @@ -105,11 +105,11 @@ Inside the copyright string, you can use the placeholder `${currentYear}` which #### deprecated -In case your project is deprecated you may also define a property `deprecated: true`. In projects that have a direct dependency to your project, UI5 Tooling will then display a deprecation warning. +In case your project is deprecated you may also define a property `deprecated: true`. In projects that have a direct dependency to your project, UI5 CLI will then display a deprecation warning. ## Resources ### Path Mapping -Depending on the project type, UI5 Tooling expects your projects source files to be located in certain directories. +Depending on the project type, UI5 CLI expects your projects source files to be located in certain directories. If your project's sources are located in different directories, you need to configure the path mapping accordingly. Depending on the type of project, there are several different path mappings available. @@ -193,7 +193,7 @@ Note that all configured paths must be written in POSIX (i.e. using only forward propertiesFileSourceEncoding: ISO-8859-1 ``` -By default UI5 Tooling expects different encodings for `*.properties` i18n files, depending on the project's specification version: +By default UI5 CLI expects different encodings for `*.properties` i18n files, depending on the project's specification version: Specification Version | Default `propertiesFileSourceEncoding` --- | --- @@ -202,7 +202,7 @@ Specification Version | Default `propertiesFileSourceEncoding` If your project uses a different encoding for `*.properties` files, you need to set the `propertiesFileSourceEncoding` configuration property. -UI5 Tooling will read the corresponding files of the project in the given encoding. Any non-ASCII characters will be replaced with the respective Unicode escape sequences. This allows you to deploy the resulting files to any environment, independent of how it expects `*.properties` files to be encoded. Please refer to [RFC 7](https://github.com/SAP/ui5-tooling/blob/main/rfcs/0007-properties-file-encoding.md) for details. +UI5 CLI will read the corresponding files of the project in the given encoding. Any non-ASCII characters will be replaced with the respective Unicode escape sequences. This allows you to deploy the resulting files to any environment, independent of how it expects `*.properties` files to be encoded. Please refer to [RFC 7](https://github.com/SAP/ui5-tooling/blob/main/rfcs/0007-properties-file-encoding.md) for details. ## Custom Configuration @@ -220,7 +220,7 @@ UI5 Tooling will read the corresponding files of the project in the given encodi otherKey: otherValue ``` -Custom configuration that is ignored by UI5 Tooling. +Custom configuration that is ignored by UI5 CLI. This can be used to store UI5 specific configuration for third-party tools. The "customConfiguration" value must be an object. @@ -258,9 +258,9 @@ If you are not sure which framework is right for you, see our [documentation on You can find an overview of the available versions for each framework here: - [**OpenUI5** Version Overview](https://openui5.hana.ondemand.com/versionoverview.html) - - *The lowest version supported by UI5 Tooling is __1.52.5__* + - *The lowest version supported by UI5 CLI is __1.52.5__* - [**SAPUI5** Version Overview](http://ui5.sap.com/versionoverview.html) - - *The lowest version supported by UI5 Tooling is __1.76.0__* + - *The lowest version supported by UI5 CLI is __1.76.0__* !!! info Projects that use the OpenUI5 framework cannot depend on projects that use the SAPUI5 framework. @@ -606,7 +606,7 @@ Note that patterns are always applied relative to the project's virtual source d httpsPort: 1443 ``` -By default, UI5 Tooling will serve applications using Port `8080`. When running in HTTP/2 or HTTPS mode, Port `8443` will be used. +By default, UI5 CLI will serve applications using Port `8080`. When running in HTTP/2 or HTTPS mode, Port `8443` will be used. If the default port is already in use, the next highest free port will be used. @@ -712,10 +712,10 @@ A list of bundle definitions. A `bundleDefinition` contains of the following opt - `addTryCatchRestartWrapper`: By default set to `false`. If set to `true`, bootable module bundles gets wrapped with a try/catch to filter "Restart" errors - `usePredefineCalls`: If set to `true`, `sap.ui.predefine` is used for UI5 modules - `numberOfParts`: By default set to `1`. The number of parts into which a module bundle should be splitted -- `sourceMap`: By default set to `true`. Adds source map support to the bundle. Available since UI5 Tooling `v3.0.0` +- `sourceMap`: By default set to `true`. Adds source map support to the bundle. Available since UI5 CLI `v3.0.0` ## Specification Versions -A project must define a specification version by setting the `specVersion` property. UI5 Tooling uses this information to detect whether the currently installed version is compatible to a project's configuration. +A project must define a specification version by setting the `specVersion` property. UI5 CLI uses this information to detect whether the currently installed version is compatible to a project's configuration. ```yaml specVersion: "3.2" @@ -733,7 +733,7 @@ All changes are documented below. ### Compatibility Matrix -Unless otherwise noted in the table below, UI5 Tooling modules are backward compatible. +Unless otherwise noted in the table below, UI5 CLI modules are backward compatible. Version | UI5 CLI Release --- | --- diff --git a/docs/pages/ESSupport.md b/docs/pages/ESSupport.md index a6aba5063ff..03a89e2c976 100644 --- a/docs/pages/ESSupport.md +++ b/docs/pages/ESSupport.md @@ -1,14 +1,15 @@ # ECMAScript Support -UI5 Tooling offers general support for `ES2022` ECMAScript features. While a `ui5 build` is executed, UI5 Tooling analyses a project's code. Depending on the project type, you have to consider some restrictions regarding the usage of certain ECMAScript syntax. +UI5 CLI offers general support for `ES2023` ECMAScript features. While a `ui5 build` is executed, UI5 CLI analyses a project's code. Depending on the project type, you have to consider some restrictions regarding the usage of certain ECMAScript syntax. -| UI5 Tooling Version | Supported ECMAScript Version | Note | +| UI5 CLI Version | Supported ECMAScript Version | Note | |-------------------- |----------------------------- | ---- | +| v3.11+ | ECMAScript 2023 | | | v3.0+ | ECMAScript 2022 | | | v2.0+ | ECMAScript 2009/ES5 | Note that code up to ECMAScript 2020 can be parsed, however required code analysis might not work correctly for specific language features | -The following section describes all restrictions grouped by the kind of ECMAScript language feature. To get more insights into the code analysing executed by UI5 Tooling check out [Code Analysis](./CodeAnalysis.md). +The following section describes all restrictions grouped by the kind of ECMAScript language feature. To get more insights into the code analysing executed by UI5 CLI check out [Code Analysis](./CodeAnalysis.md). ## Language Features with Restrictions @@ -16,9 +17,9 @@ The following sections describe the restrictions grouped by the ECMAScript langu ### JavaScript modules -In general, UI5 Tooling only analyzes **JavaScript** files of type `script`. [JavaScript Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) are not analyzed. +In general, UI5 CLI only analyzes **JavaScript** files of type `script`. [JavaScript Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) are not analyzed. -UI5 Tooling and the UI5 Runtime does not support the usage of `export` and `import` of JavaScript Modules. Therefore, `sap.ui.define` has to be used. +UI5 CLI and the UI5 Runtime does not support the usage of `export` and `import` of JavaScript Modules. Therefore, `sap.ui.define` has to be used. === "Supported" @@ -41,7 +42,7 @@ UI5 Tooling and the UI5 Runtime does not support the usage of `export` and `impo ### Template Literal -[Template Literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) without an expressions can be used in all places where string literals can be used. However, since UI5 Tooling will attempt a static code analysis for certain calls to UI5 API, Template Literals with one or more expressions (e.g. `Hello ${planets[2]}`) can't be used in the scenarios described below. +[Template Literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) without an expressions can be used in all places where string literals can be used. However, since UI5 CLI will attempt a static code analysis for certain calls to UI5 API, Template Literals with one or more expressions (e.g. `Hello ${planets[2]}`) can't be used in the scenarios described below. #### Template Literal in `sap.ui.define` or `sap.ui.require` @@ -121,7 +122,7 @@ When declaring a **Smart Template** using a **Template Literal** with one or mor #### Template Literal in XMLComposite Declaration -The **XMLComposite** control is deprecated since version UI5 1.88. Nevertheless UI5 Tooling will attempt to analyze the declaration of any such controls in a project. +The **XMLComposite** control is deprecated since version UI5 1.88. Nevertheless UI5 CLI will attempt to analyze the declaration of any such controls in a project. Declaring an **XMLComposite** control using a **Template Literal** with one or more expressions in the name, is not supported. @@ -169,7 +170,7 @@ A library is typically initialized via an accompanying `library.js`. Within that #### Reserved Variable Names in a Template Literal -While UI5 Tooling performs a build placeholders are replaced with a values offered by the build. For example `${version}` is replaced with the actual version defined in the package.json of the project. Therefore it is required to not use any **Template Literal** where any expression contains variable with following names: +While UI5 CLI performs a build placeholders are replaced with a values offered by the build. For example `${version}` is replaced with the actual version defined in the package.json of the project. Therefore it is required to not use any **Template Literal** where any expression contains variable with following names: - `version` - `project.version` @@ -190,7 +191,7 @@ While UI5 Tooling performs a build placeholders are replaced with a values offer const transformedVersion `v${version}` ``` -UI5 Tooling searches for the exact match of `${version}`, so with adding whitespaces before and after the variable name `${ version }` UI5 Tooling won't replace this occurence. This can be enforced by the dedicated ESLint config [template-curly-spacing](https://eslint.org/docs/latest/rules/template-curly-spacing) with option `always`. +UI5 CLI searches for the exact match of `${version}`, so with adding whitespaces before and after the variable name `${ version }` UI5 CLI won't replace this occurence. This can be enforced by the dedicated ESLint config [template-curly-spacing](https://eslint.org/docs/latest/rules/template-curly-spacing) with option `always`. ### Spread Element @@ -275,7 +276,7 @@ When declaring a **Smart Template**, the usage of a **Spread Element** in the co #### Spread Element in XMLComposite Declaration -The **XMLComposite** control is deprecated since version UI5 1.88. Nevertheless UI5 Tooling will attempt to analyze the declaration of any such controls in a project. +The **XMLComposite** control is deprecated since version UI5 1.88. Nevertheless UI5 CLI will attempt to analyze the declaration of any such controls in a project. When declaring an **XMLComposite**, the usage of a **Spread Element** in the configuration is not supported. @@ -410,7 +411,7 @@ When declaring a **Smart Template**, the usage of an **Object Expression** in th #### Object Expression in XMLComposite Declaration -The **XMLComposite** control is deprecated since version UI5 1.88. Nevertheless UI5 Tooling will attempt to analyze the declaration of any such controls in a project. +The **XMLComposite** control is deprecated since version UI5 1.88. Nevertheless UI5 CLI will attempt to analyze the declaration of any such controls in a project. When declaring an **XMLComposite**, the usage of an **Object Expression** in the configuration is not supported. diff --git a/docs/pages/FAQ.md b/docs/pages/FAQ.md index 1320518b6b5..437559f2db4 100644 --- a/docs/pages/FAQ.md +++ b/docs/pages/FAQ.md @@ -8,21 +8,21 @@ Please follow our [Contribution Guidelines](https://github.com/SAP/ui5-tooling/b ### What's the Difference Between OpenUI5 and SAPUI5? The open source project [OpenUI5](https://openui5.org/) provides most of the fundamental framework features. [SAPUI5](https://ui5.sap.com/) enhances this by providing **additional libraries** under a **different license**. -OpenUI5 is provided under the Apache 2.0 license. The SAPUI5 packages that are consumed in UI5 Tooling are provided under the terms of the [SAP Developer License Agreement](https://tools.hana.ondemand.com/developer-license-3.1.txt). +OpenUI5 is provided under the Apache 2.0 license. The SAPUI5 packages that are consumed in UI5 CLI are provided under the terms of the [SAP Developer License Agreement](https://tools.hana.ondemand.com/developer-license-3.1.txt). Note that projects which use the OpenUI5 framework cannot depend on projects that use the SAPUI5 framework. However, SAPUI5 projects can depend on OpenUI5 projects. Please also see the [UI5 SDK documentation "SAPUI5 vs. OpenUI5"](https://ui5.sap.com/#/topic/5982a9734748474aa8d4af9c3d8f31c0). ### Why package.json? / Why npm? -Currently, the tooling can only resolve dependencies defined in a `package.json` file. This might change in the future by adding Translators for additional dependency management systems. +Currently, UI5 CLI can only resolve dependencies defined in a `package.json` file. This might change in the future by adding Translators for additional dependency management systems. -To manage your dependencies, you can use almost any `Node.js` package manager that relies on `package.json` files. Popular ones are [npm](https://www.npmjs.com/), [Yarn](https://yarnpkg.com/) and [pnpm](https://pnpm.js.org/). UI5 Tooling itself uses [npm](https://www.npmjs.com/). +To manage your dependencies, you can use almost any `Node.js` package manager that relies on `package.json` files. Popular ones are [npm](https://www.npmjs.com/), [Yarn](https://yarnpkg.com/) and [pnpm](https://pnpm.js.org/). UI5 CLI itself uses [npm](https://www.npmjs.com/). -UI5 Tooling resolves dependencies almost the same way `Node.js` does when executing a `require` / `import` statement. +UI5 CLI resolves dependencies almost the same way `Node.js` does when executing a `require` / `import` statement. ### Where are the npm Packages? * [OpenUI5 Libraries](https://www.npmjs.com/org/openui5) * [SAPUI5 Libraries](https://www.npmjs.com/org/sapui5) -* [UI5 Tooling Modules](https://www.npmjs.com/org/ui5) +* [UI5 CLI Modules](https://www.npmjs.com/org/ui5) diff --git a/docs/pages/GettingStarted.md b/docs/pages/GettingStarted.md index 8a7fbdd0c2d..3969b031cc0 100644 --- a/docs/pages/GettingStarted.md +++ b/docs/pages/GettingStarted.md @@ -15,27 +15,27 @@ npm install --save-dev @ui5/cli ui5 --help ``` -The globally installed UI5 CLI will always try to invoke a locally installed version of the UI5 CLI (if present). This way you can use different versions of the UI5 Tooling across your projects. Please see the [UI5 CLI documentation](./CLI.md#local-vs-global-installation) for details. +The globally installed UI5 CLI will always try to invoke a locally installed version of the UI5 CLI (if present). This way you can use different versions of the UI5 CLI across your projects. Please see the [UI5 CLI documentation](./CLI.md#local-vs-global-installation) for details. ## ⚑️ Quick Start: OpenUI5 Sample App -Check out the [OpenUI5 Sample App](https://github.com/SAP/openui5-sample-app) featuring a full blown [How-to](https://github.com/SAP/openui5-sample-app/#openui5-sample-app) to play around with UI5 Tooling! +Check out the [OpenUI5 Sample App](https://github.com/SAP/openui5-sample-app) featuring a full blown [How-to](https://github.com/SAP/openui5-sample-app/#openui5-sample-app) to play around with UI5 CLI! ## Starting a New Project The easiest way to start a new UI5 project is to use a template generator like [**generator-easy-ui5**](https://github.com/SAP/generator-easy-ui5). Choose a template that is designed for the type of project you want to create and the target environment where you want to deploy it to. -Make sure that the template already uses UI5 Tooling. A good indicator for that is the presence of a `ui5.yaml` file in the generated project. +Make sure that the template already uses UI5 CLI. A good indicator for that is the presence of a `ui5.yaml` file in the generated project. When working with SAP Business Application Studio, there are several templates available to you. Check out the tutorial on creating a basic SAPUI5 application and deploying it to Cloud Foundry from within SAP Business Application Studio: [Create an SAP Fiori App Using SAP Business Application Studio](https://developers.sap.com/tutorials/appstudio-fioriapps-create.html) You can find many guides on UI5 development with SAP Business Application Studio in the [Tutorial Navigator](https://developers.sap.com/tutorial-navigator.html?tag=topic:sapui5&tag=products:technology-platform/sap-business-application-studio). ## Enabling an Existing Project -You can easily check whether or not a project (application or library) can already be used with the UI5 Tooling by looking for a `ui5.yaml` file in the project's root directory. -This file (with some exceptions) is required for all projects and their dependencies (e.g. reuse libraries) to use them in the UI5 Tooling. +You can easily check whether or not a project (application or library) can already be used with the UI5 CLI by looking for a `ui5.yaml` file in the project's root directory. +This file (with some exceptions) is required for all projects and their dependencies (e.g. reuse libraries) to use them in the UI5 CLI. ### Setup -If your project is not set up for use with the UI5 Tooling yet, follow these steps: +If your project is not set up for use with the UI5 CLI yet, follow these steps: 1. If your project does not have a `package.json` file, let npm generate it: ```sh @@ -92,8 +92,8 @@ If your project is not set up for use with the UI5 Tooling yet, follow these ste 1. If you are using Git or similar version control, commit `package.json` and `ui5.yaml` to your repository. ```sh git add package.json ui5.yaml - git commit -m "Enable use with UI5 Tooling" + git commit -m "Enable use with UI5 CLI" ``` -**Hooray! You can now use UI5 Tooling in your project!** +**Hooray! You can now use UI5 CLI in your project!** {: .sap-icon-ui5-after } diff --git a/docs/pages/OpenUI5.md b/docs/pages/OpenUI5.md index bfaad71b454..0eeadd6a9dc 100644 --- a/docs/pages/OpenUI5.md +++ b/docs/pages/OpenUI5.md @@ -1,13 +1,13 @@ # Consuming OpenUI5 Libraries -OpenUI5 consumption with UI5 Tooling is very similar to SAPUI5 consumption. Please refer to the documentation on [Consuming SAPUI5 Libraries](./SAPUI5.md) for a general description of how UI5 Tooling can fetch and provide framework dependencies to your project. +OpenUI5 consumption with UI5 CLI is very similar to SAPUI5 consumption. Please refer to the documentation on [Consuming SAPUI5 Libraries](./SAPUI5.md) for a general description of how UI5 CLI can fetch and provide framework dependencies to your project. Note that projects using the SAPUI5 framework can depend on projects using the OpenUI5 framework. However, OpenUI5 projects can't depend on SAPUI5 projects. Please also refer to our documentation on the [differences between OpenUI5 and SAPUI5](./FAQ.md#whats-the-difference-between-openui5-and-sapui5). !!! info - The minimum OpenUI5 version that can be consumed by UI5 Tooling is **1.52.5** + The minimum OpenUI5 version that can be consumed by UI5 CLI is **1.52.5** ## Configuration Your project's `ui5.yaml` provides a configuration section dedicated to framework dependency handling. diff --git a/docs/pages/Overview.md b/docs/pages/Overview.md index ae01cc5199d..0c544f47560 100644 --- a/docs/pages/Overview.md +++ b/docs/pages/Overview.md @@ -5,14 +5,14 @@ However, you might have good reasons to also use the UI5 Builder during developm ## Project Dependencies -UI5 Tooling differentiates between "framework dependencies" and "project dependencies". +UI5 CLI differentiates between "framework dependencies" and "project dependencies". -**Framework dependencies** are generally libraries and themes provided by the SAP frameworks "OpenUI5" and "SAPUI5". UI5 Tooling will take care of downloading them and handling their versions for you. Please see the corresponding documentation on both options: +**Framework dependencies** are generally libraries and themes provided by the SAP frameworks "OpenUI5" and "SAPUI5". UI5 CLI will take care of downloading them and handling their versions for you. Please see the corresponding documentation on both options: * [Working with **OpenUI5** Framework Dependencies](./OpenUI5.md) * [Working with **SAPUI5** Framework Dependencies](./SAPUI5.md) -**Project dependencies** are all other libraries, custom themes, UI5 Tooling extensions or JavaScript modules your project depends on. In general these dependencies are maintained in the package.json of your project. See also: [FAQ: Why package.json? / Why npm?](./FAQ.md#why-packagejson-why-npm). +**Project dependencies** are all other libraries, custom themes, UI5 CLI extensions or JavaScript modules your project depends on. In general these dependencies are maintained in the package.json of your project. See also: [FAQ: Why package.json? / Why npm?](./FAQ.md#why-packagejson-why-npm). ## Linking Projects Would you like to work on an application project and one or more of its dependencies at the same time? We got you covered! @@ -94,7 +94,7 @@ That's it. You can check whether the linking worked by executing `ui5 tree` in t As an alternative to defining your project dependencies in the `package.json`, you can define a static dependency hierarchy for the project in a YAML file. This is typically only advised in special cases where none of the other concepts work. -To use such a file in UI5 CLI, provide a path to it using the [`--dependency-definition`](./CLI.md#common-options) parameter. Note that all `package.json` dependencies will be ignored (including UI5 Tooling extensions), but UI5 framework dependencies defined in `ui5.yaml` will still be used. +To use such a file in UI5 CLI, provide a path to it using the [`--dependency-definition`](./CLI.md#common-options) parameter. Note that all `package.json` dependencies will be ignored (including UI5 CLI extensions), but UI5 framework dependencies defined in `ui5.yaml` will still be used. **Example: `projectDependencies.yaml`** @@ -113,7 +113,7 @@ By placing this file in the root directory of the `my.app` application project, The structure of the dependency definition file follows that of the [`@ui5/project/graph/providers/DependencyTree~TreeNode`](https://sap.github.io/ui5-tooling/stable/api/@ui5_project_graph_providers_DependencyTree.html#~TreeNode) type. ## HTTP/2 Development Webserver -The UI5 Tooling contains a web server to serve the project via HTTP/2 protocol. +The UI5 CLI contains a web server to serve the project via HTTP/2 protocol. ```sh ui5 serve --h2 @@ -122,6 +122,6 @@ ui5 serve --h2 This requires an SSL certificate. You are guided through the automatic generation process. Also see the [UI5 Server documentation](./Server.md#ssl-certificates) ## Integration in Other Tools -One of the key features of the UI5 Tooling is its modularization. Single parts of the tooling can easily be integrated in other `Node.js`-based tools and frameworks like [Grunt](https://gruntjs.com/) or [Gulp](https://gulpjs.com/). +One of the key features of the UI5 CLI is its modularization. Single parts of UI5 CLI can easily be integrated in other `Node.js`-based tools and frameworks like [Grunt](https://gruntjs.com/) or [Gulp](https://gulpjs.com/). All JavaScript APIs available for direct consumption are listed [here](https://sap.github.io/ui5-tooling/v3/api/index.html). However, for standard UI5 development, the [UI5 CLI](./CLI.md) should always be the first choice. diff --git a/docs/pages/Project.md b/docs/pages/Project.md index 6ac60bc0306..215100f3468 100644 --- a/docs/pages/Project.md +++ b/docs/pages/Project.md @@ -15,7 +15,7 @@ The source directory of an application (typically named `webapp`) is mapped to t An applications source directory may or may not contain a `Component.js` file. If it does, it must also contain a `manifest.json` file. If there is a `Component.js` file, an optimized `Component-preload.js` file will be generated during the build. ### library -UI5 libraries are often referred to as reuse-, custom- or [control libraries](https://github.com/SAP/openui5/blob/main/docs/controllibraries.md). They are a key component in sharing code across multiple projects in UI5. +UI5 libraries are often referred to as reuse-, custom- or [control libraries](https://github.com/SAP/openui5/blob/-/docs/controllibraries.md). They are a key component in sharing code across multiple projects in UI5. A project of type `library` must have a source directory (typically named `src`). It may also feature a "test" directory. These directories are mapped to the virtual directories `/resources` for the sources and `/test-resources` for the test resources. diff --git a/docs/pages/SAPUI5.md b/docs/pages/SAPUI5.md index 87a06768b0e..7e8c5487a0e 100644 --- a/docs/pages/SAPUI5.md +++ b/docs/pages/SAPUI5.md @@ -3,20 +3,20 @@ !!! info Make sure you have installed the UI5 CLI in Version 2.0 or later: `npm install --global @ui5/cli` - The minimum version of SAPUI5 that can be consumed by UI5 Tooling as described below is **1.76.0.** + The minimum version of SAPUI5 that can be consumed by UI5 CLI as described below is **1.76.0.** For lower versions, consider using the [CDN bootstrap](https://ui5.sap.com/#/topic/2d3eb2f322ea4a82983c1c62a33ec4ae) or a custom middleware like [ui5-middleware-simpleproxy](https://www.npmjs.com/package/ui5-middleware-simpleproxy). ## Overview -SAPUI5 libraries are hosted on the public npm registry at `registry.npmjs.org`. However, you should not install them using node package managers such as npm. Let UI5 Tooling handle them instead by following this guide. +SAPUI5 libraries are hosted on the public npm registry at `registry.npmjs.org`. However, you should not install them using node package managers such as npm. Let UI5 CLI handle them instead by following this guide. !!! note - For more background information also see the Blog Post ["UI5ers Buzz #49: The UI5 Tooling and SAPUI5 – The Next Step"](https://blogs.sap.com/2020/04/01/ui5ers-buzz-49-the-ui5-tooling-and-sapui5-the-next-step/) + For more background information also see the Blog Post ["UI5ers Buzz #49: The UI5 CLI and SAPUI5 – The Next Step"](https://blogs.sap.com/2020/04/01/ui5ers-buzz-49-the-ui5-tooling-and-sapui5-the-next-step/) ## Usage Since Version 2.0 of the UI5 CLI, it will automatically download all required framework dependencies of a project that have been listed in the corresponding `ui5.yaml` file. They will be cached in a `.ui5` directory located in the user's home directory. This happens transparently whenever you execute the `ui5 serve` or `ui5 build` commands. -All non-framework dependencies, such as reuse libraries or UI5 Tooling extensions, still need to be maintained as npm dependencies in the projects `package.json`. At the same time, framework dependencies listed in the `ui5.yaml` should not be listed in the `package.json` as they will be ignored by the UI5 Tooling. +All non-framework dependencies, such as reuse libraries or UI5 CLI extensions, still need to be maintained as npm dependencies in the projects `package.json`. At the same time, framework dependencies listed in the `ui5.yaml` should not be listed in the `package.json` as they will be ignored by the UI5 CLI. ## Configuration diff --git a/docs/pages/Troubleshooting.md b/docs/pages/Troubleshooting.md index 960c8e10418..3c135cc6f6b 100644 --- a/docs/pages/Troubleshooting.md +++ b/docs/pages/Troubleshooting.md @@ -22,7 +22,7 @@ Remove the `.ui5/framework/` directory from your user's home directory: rm -rf ~/.ui5/framework/ ``` -Any missing framework dependencies will be downloaded again during the next UI5 Tooling invocation. +Any missing framework dependencies will be downloaded again during the next UI5 CLI invocation. ## Environment Variables ### Changing the Log Level @@ -31,7 +31,7 @@ In CI environments or in a combination with other tools, the usage of [UI5 CLI's #### Resolution -Replace UI5 Tooling's `--log-level` option with the `UI5_LOG_LVL` environment variable. +Replace UI5 CLI's `--log-level` option with the `UI5_LOG_LVL` environment variable. Example: @@ -53,9 +53,9 @@ UI5 + Karma: !!! warning The combination of the `UI5_LOG_LVL` environment variable with the `--log-level` CLI parameter might lead to unexpected results; they should be used interchangeably but not together. The CLI parameter takes precedence over the `UI5_LOG_LVL` environment variable. -### Changing UI5 Tooling's Data Directory +### Changing UI5 CLI's Data Directory -UI5 Tooling's data directory is by default at `~/.ui5`. It's the place where the framework artifacts are stored. +UI5 CLI's data directory is by default at `~/.ui5`. It's the place where the framework artifacts are stored. In some cases and environments this is not a convenient location and the user needs to provide a better one. The path to it can either be provided via environment variable or permanently set in the configuration. diff --git a/docs/pages/Workspace.md b/docs/pages/Workspace.md index ad53d886768..23da13e1dd9 100644 --- a/docs/pages/Workspace.md +++ b/docs/pages/Workspace.md @@ -103,16 +103,16 @@ dependencyManagement: - path: ../test.library ``` -Resolution paths will be used by UI5 Tooling to look for project dependencies. Any dependencies found via these paths will be used over the ones found with the regular dependency resolution mechanism. This includes UI5 Tooling extensions. +Resolution paths will be used by UI5 CLI to look for project dependencies. Any dependencies found via these paths will be used over the ones found with the regular dependency resolution mechanism. This includes UI5 CLI extensions. -Paths must point to a directory containing a `package.json`. UI5 Tooling will attempt to find a UI5 project here. However, if the `package.json` contains a [`workspaces`](https://docs.npmjs.com/cli/v8/using-npm/workspaces), or equivalently, `ui5.workspaces` configuration (which overrules the first), UI5 Tooling will resolve the workspace first and attempt to find UI5 projects in the configured "npm workspaces". This is commonly used in mono-repos. An example can be found in the [OpenUI5 repository](https://github.com/SAP/openui5/blob/b4267488e5d3546de4cd9577ccac4208482d71e0/package.json#L130-L132). +Paths must point to a directory containing a `package.json`. UI5 CLI will attempt to find a UI5 project here. However, if the `package.json` contains a [`workspaces`](https://docs.npmjs.com/cli/v8/using-npm/workspaces), or equivalently, `ui5.workspaces` configuration (which overrules the first), UI5 CLI will resolve the workspace first and attempt to find UI5 projects in the configured "npm workspaces". This is commonly used in mono-repos. An example can be found in the [OpenUI5 repository](https://github.com/SAP/openui5/blob/b4267488e5d3546de4cd9577ccac4208482d71e0/package.json#L130-L132). Paths must be written in POSIX (i.e. using only forward slashes `/` as path segment separators) and must be **relative to the workspace configuration file**. Absolute paths, or paths relative to the home directory (`~`), are not allowed. This is to ensure that workspace configuration files are easy to share and to reduce the chance of them exposing sensitive information like user names or large directory hierarchies. Symbolic links are followed. Note that this configuration only affects the resolution of dependencies which have already been found during the regular dependency resolution process of a project. For example, if a workspace resolution path resolves to a project that would otherwise not be part of the dependency tree of the current root project, it will not be added to the dependency tree. Also, transitive dependencies of resolved projects are not being followed. ## Workspace Specification Versions -A workspace configuration must define a Specification Version by setting the `specVersion` property. UI5 Tooling uses this information to detect whether the currently installed version is compatible with a workspace's configuration. +A workspace configuration must define a Specification Version by setting the `specVersion` property. UI5 CLI uses this information to detect whether the currently installed version is compatible with a workspace's configuration. ```yaml specVersion: "workspace/1.0" @@ -130,7 +130,7 @@ All changes are documented below. ### Compatibility Matrix -Unless otherwise noted in the table below, UI5 Tooling modules are backward-compatible. +Unless otherwise noted in the table below, UI5 CLI modules are backward-compatible. Version | UI5 CLI Release --- | --- diff --git a/docs/pages/extensibility/CustomServerMiddleware.md b/docs/pages/extensibility/CustomServerMiddleware.md index 1968cd2dc17..ed4dfd68fb1 100644 --- a/docs/pages/extensibility/CustomServerMiddleware.md +++ b/docs/pages/extensibility/CustomServerMiddleware.md @@ -245,11 +245,11 @@ In this case, a `middlewareUtil` object is provided as a part of the custom midd !!! Warning The Karma project has been [deprecated](https://github.com/karma-runner/karma#karma-is-deprecated-and-is-not-accepting-new-features-or-general-bug-fixes) as of 2023 -[`karma-ui5`](https://github.com/SAP/karma-ui5) is a plugin for the popular [Karma test runner](https://karma-runner.github.io/). Based on your [configuration](https://github.com/SAP/karma-ui5#url), it can fetch resources from a dedicated server or start an internal server using parts of UI5 Tooling. +[`karma-ui5`](https://github.com/SAP/karma-ui5) is a plugin for the popular [Karma test runner](https://karma-runner.github.io/). Based on your [configuration](https://github.com/SAP/karma-ui5#url), it can fetch resources from a dedicated server or start an internal server using parts of UI5 CLI. In the latter case, any custom middleware configured in the default `ui5.yaml` of the project will be used automatically. -However, since Karma uses the [`connect`](https://github.com/senchalabs/connect) framework, as opposed to UI5 Tooling's [`express`](https://github.com/expressjs/express), custom middleware might not always work as expected. Compared to `connect`, the `express` framework provides a more versatile API to middleware. +However, since Karma uses the [`connect`](https://github.com/senchalabs/connect) framework, as opposed to UI5 CLI's [`express`](https://github.com/expressjs/express), custom middleware might not always work as expected. Compared to `connect`, the `express` framework provides a more versatile API to middleware. Therefore, if you plan to use custom middleware in an integrated scenario with `karma-ui5`, you must **restrict the middleware to using the [`connect`](https://github.com/senchalabs/connect) API only** to ensure compatibility. diff --git a/docs/pages/extensibility/CustomTasks.md b/docs/pages/extensibility/CustomTasks.md index 4d8dc7a2356..7c5da3b8841 100644 --- a/docs/pages/extensibility/CustomTasks.md +++ b/docs/pages/extensibility/CustomTasks.md @@ -192,17 +192,17 @@ A custom task implementation needs to return a function with the following signa !!! info This functionality has been added with UI5 CLI [`v3.0.0`](https://github.com/SAP/ui5-cli/releases/tag/v3.0.0) -Custom tasks can export an optional callback function `determineRequiredDependencies` to control which dependency-resources are made available through the `dependencies`-reader that is provided to the task. By reducing the amount of required dependencies or by not requiring any, UI5 Tooling might be able to build a project faster. +Custom tasks can export an optional callback function `determineRequiredDependencies` to control which dependency-resources are made available through the `dependencies`-reader that is provided to the task. By reducing the amount of required dependencies or by not requiring any, UI5 CLI might be able to build a project faster. -Before executing a task, UI5 Tooling will ensure that all required dependencies have been built. +Before executing a task, UI5 CLI will ensure that all required dependencies have been built. -If this callback is not provided, UI5 Tooling will make an assumption as to whether the custom task requires access to any resources of dependencies based on the defined Specification Version of the custom task extension: +If this callback is not provided, UI5 CLI will make an assumption as to whether the custom task requires access to any resources of dependencies based on the defined Specification Version of the custom task extension: -* **Specification Version 3.0 and later:** If no callback is provided, UI5 Tooling assumes that no dependencies are required. In this case, the `dependencies` parameter will be omitted. -* **Specification Versions before 3.0:** If no callback is provided, UI5 Tooling assumes that all dependencies are required. +* **Specification Version 3.0 and later:** If no callback is provided, UI5 CLI assumes that no dependencies are required. In this case, the `dependencies` parameter will be omitted. +* **Specification Versions before 3.0:** If no callback is provided, UI5 CLI assumes that all dependencies are required. -*For more details, see also [RFC 0012 UI5 Tooling Extension API v3](https://github.com/SAP/ui5-tooling/blob/rfc-ui5-tooling-extension-api-v3/rfcs/0012-UI5-Tooling-Extension-API-3.md#3-tasks-requiring-dependencies)* +*For more details, see also [RFC 0012 UI5 CLI Extension API v3](https://github.com/SAP/ui5-tooling/blob/rfc-ui5-tooling-extension-api-v3/rfcs/0012-UI5-Tooling-Extension-API-3.md#3-tasks-requiring-dependencies)* === "ESM" @@ -228,7 +228,7 @@ If this callback is not provided, UI5 Tooling will make an assumption as to whet * @returns {Promise} * Promise resolving with a Set containing all dependencies * that should be made available to the task. - * UI5 Tooling will ensure that those dependencies have been + * UI5 CLI will ensure that those dependencies have been * built before executing the task. */ export async function determineRequiredDependencies({availableDependencies, getDependencies, getProject, options}) { @@ -269,7 +269,7 @@ If this callback is not provided, UI5 Tooling will make an assumption as to whet * @returns {Promise} * Promise resolving with a Set containing all dependencies * that should be made available to the task. - * UI5 Tooling will ensure that those dependencies have been + * UI5 CLI will ensure that those dependencies have been * built before executing the task. */ module.exports.determineRequiredDependencies = async function({availableDependencies, getDependencies, getProject, options}) { @@ -359,9 +359,9 @@ result by writing them into the provided `workspace`. ``` !!! warning - Depending on your project setup, UI5 Tooling tends to open many files simultaneously during a build. To prevent errors like `EMFILE: too many open files`, we urge custom task implementations to use the [graceful-fs](https://github.com/isaacs/node-graceful-fs#readme) module as a drop-in replacement for the native `fs` module in case it is used. + Depending on your project setup, UI5 CLI tends to open many files simultaneously during a build. To prevent errors like `EMFILE: too many open files`, we urge custom task implementations to use the [graceful-fs](https://github.com/isaacs/node-graceful-fs#readme) module as a drop-in replacement for the native `fs` module in case it is used. - Tasks should ideally use the reader/writer APIs provided by UI5 Tooling for working with project resources. + Tasks should ideally use the reader/writer APIs provided by UI5 CLI for working with project resources. ### Example: lib/tasks/compileLicenseSummary.js diff --git a/docs/pages/extensibility/ProjectShims.md b/docs/pages/extensibility/ProjectShims.md index 80a04fac7a5..bbc201035e1 100644 --- a/docs/pages/extensibility/ProjectShims.md +++ b/docs/pages/extensibility/ProjectShims.md @@ -1,5 +1,5 @@ ### Project Shims -A project shim extension can be used to define or extend a project configuration of a module. The most popular use case is probably to add UI5 project configuration to a third party module that otherwise could not be used with the UI5 Tooling. +A project shim extension can be used to define or extend a project configuration of a module. The most popular use case is probably to add UI5 project configuration to a third party module that otherwise could not be used with the UI5 CLI. Also see [RFC 0002 Project Shims](https://github.com/SAP/ui5-tooling/blob/main/rfcs/0002-project-shims.md). diff --git a/docs/updates/migrate-v1.md b/docs/updates/migrate-v1.md index 91d553e1e19..4b2489f316a 100644 --- a/docs/updates/migrate-v1.md +++ b/docs/updates/migrate-v1.md @@ -1,6 +1,6 @@ # Migrate to v1 -v1.0.0 is the first stable release of the UI5 Tooling. There are only a few notable changes to the 0.x alpha version. +v1.0.0 is the first stable release of the UI5 CLI. There are only a few notable changes to the 0.x alpha version. ## Breaking changes diff --git a/docs/updates/migrate-v2.md b/docs/updates/migrate-v2.md index 66317a40f9a..d7062e5a050 100644 --- a/docs/updates/migrate-v2.md +++ b/docs/updates/migrate-v2.md @@ -1,15 +1,15 @@ # Migrate to v2 -v2.0.0 of the UI5 Tooling was released on April 1, 2020. As a major feature, it introduces the easy consumption of SAPUI5 libraries in UI5 projects. +v2.0.0 of the UI5 CLI was released on April 1, 2020. As a major feature, it introduces the easy consumption of SAPUI5 libraries in UI5 projects. ## Breaking changes -**All UI5 Tooling Modules: Require Node.js >= 10** +**All UI5 CLI Modules: Require Node.js >= 10** Support for older Node.js releases has been dropped. **UI5 Builder: Make namespace mandatory for application and library projects ([SAP/ui5-builder#430](https://github.com/SAP/ui5-builder/pull/430))** -The UI5 Tooling must be able to determine an application- or library project's namespace. Otherwise an error is thrown. +The UI5 CLI must be able to determine an application- or library project's namespace. Otherwise an error is thrown. Ideally the namespace should be defined in the `sap.app/id` field of the [`manifest.json`](https://ui5.sap.com/#/topic/be0cf40f61184b358b5faedaec98b2da) diff --git a/docs/updates/migrate-v3.md b/docs/updates/migrate-v3.md index b9f45e908c4..5199a5635d9 100644 --- a/docs/updates/migrate-v3.md +++ b/docs/updates/migrate-v3.md @@ -1,11 +1,11 @@ # Migrate to v3 !!! tip "Now Released" - **UI5 Tooling 3.0 has been released February 9, 2023 πŸŽ‰** + **UI5 CLI 3.0 has been released February 9, 2023 πŸŽ‰** Install the latest version via: `npm i --save-dev @ui5/cli@latest` - And find the announcement blog post here: **[SAP Community: UI5 Tooling 3.0](https://blogs.sap.com/2023/02/10/ui5-tooling-3.0/)** + And find the announcement blog post here: **[SAP Community: UI5 CLI 3.0](https://blogs.sap.com/2023/02/10/ui5-tooling-3.0/)** ## Node.js and npm Version Support @@ -22,7 +22,7 @@ This means your old projects might still work. Unless they have non-standard con ## Changes for Projects !!! info - βœ… Projects defining **Specification Version 2.x** are expected to be **fully compatible with UI5 Tooling v3** + βœ… Projects defining **Specification Version 2.x** are expected to be **fully compatible with UI5 CLI v3** For projects defining the latest **Specification Versions 3.0 and higher**, some changes apply: @@ -33,7 +33,7 @@ See also [Configuration: Specification Version 3.0](../pages/Configuration.md#sp ## Changes for Extensions !!! info - βœ… Custom Tasks and Custom Middleware defining **Specification Version 2.x** are expected to be **fully compatible with UI5 Tooling v3** + βœ… Custom Tasks and Custom Middleware defining **Specification Version 2.x** are expected to be **fully compatible with UI5 CLI v3** For extensions defining the latest **Specification Versions 3.0 and higher**, some changes and improvements apply: @@ -47,7 +47,7 @@ For extensions defining the latest **Specification Versions 3.0 and higher**, so ## Changes to Dependency Configuration !!! info - βœ… The **`ui5.dependencies` package.json configuration** becomes obsolete and is ignored in UI5 Tooling v3. + βœ… The **`ui5.dependencies` package.json configuration** becomes obsolete and is ignored in UI5 CLI v3. Configuration like the following is not needed anymore: @@ -64,7 +64,7 @@ For extensions defining the latest **Specification Versions 3.0 and higher**, so ``` `dependencies`, `devDependencies` and `optionalDependencies` are now [automatically analyzed](https://github.com/SAP/ui5-project/blob/ff04ae4aeeb7f7d889dffd0c0e3e8774dd708c79/lib/graph/providers/NodePackageDependencies.js#L104). - If a dependency can be configured as a UI5 project or UI5 Tooling extension, it is added to the graph and its `dependencies` are analyzed. + If a dependency can be configured as a UI5 project or UI5 CLI extension, it is added to the graph and its `dependencies` are analyzed. Note that `devDependencies` and `optionalDependencies` are ignored for all but the current root project. For projects that are intended to be consumed in other projects (for example libraries), this means that any required custom tasks must be added to `dependencies`. @@ -78,7 +78,7 @@ Also the @ui5/server API has been changed. Instead of a `tree`, it now only acce ### Migrate Your Code -The tooling modules such as @ui5/builder, etc. have been transformed to ES Modules ("ESM"). Therefore, they no longer use a CommonJS export and cannot be included via `require`. +The UI5 CLI-related modules such as @ui5/builder, etc. have been transformed to ES Modules ("ESM"). Therefore, they no longer use a CommonJS export and cannot be included via `require`. If your code is in CommonJS format, it needs to use dynamic imports or be converted to [ES Modules](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). @@ -139,11 +139,11 @@ The `jsdocGenerator` processor and the corresponding `generateJsdoc` task will n ## Always Building Required Dependencies -If any of a project's build tasks requires access to resources of the project's dependencies, UI5 Tooling v3 will now **always build that dependency upfront**. +If any of a project's build tasks requires access to resources of the project's dependencies, UI5 CLI v3 will now **always build that dependency upfront**. This ensures that tasks always access processed resources and never the raw sources of a dependency. Resulting in better reproducibility of build results and resolving common issues. -Especially for projects of type `library`, where standard tasks like [`buildThemes`](https://github.com/SAP/ui5-project/blob/b40e3f569e0f01c6dd8e72141c7ba43449812d01/lib/build/definitions/library.js#L139) always require dependency access, UI5 Tooling will now always build all dependencies. +Especially for projects of type `library`, where standard tasks like [`buildThemes`](https://github.com/SAP/ui5-project/blob/b40e3f569e0f01c6dd8e72141c7ba43449812d01/lib/build/definitions/library.js#L139) always require dependency access, UI5 CLI will now always build all dependencies. In the future, a caching mechanism should help and improve build times with this new behavior. @@ -169,7 +169,7 @@ The following processors have been removed: **Task Migration** -| UI5 Tooling v2 | UI5 Tooling v3 | Note | +| UI5 CLI v2 | UI5 CLI v3 | Note | | --------------------------- | --------------------------- | ------------------------- | | createDebugFiles
uglify | minify | The minify task is executed earlier, before the bundling process takes place. Any existing `beforeTask` or `afterTask` configuration of custom tasks might need to be adapted to cater for this change.
To adapt, you can use the `generateResourcesJson` task for subscription before or after the last standard task. By default, `generateResourcesJson` is disabled, but you can still subscribe to it, thereby ensuring that your custom tasks execute in the correct order. | | generateVersionInfo | generateVersionInfo | The task is no longer executed by default for application projects. It can be re-enabled by using the `--include-task` parameter. | @@ -221,6 +221,6 @@ The following middleware has been removed from the [standard middlewares list](. **Middleware Migration** -| UI5 Tooling v2 | UI5 Tooling v3 | Note | +| UI5 CLI v2 | UI5 CLI v3 | Note | | --------------------------- | --------------------------- | ------------------------- | | connectUi5Proxy | *None* | More sophisticated proxy solutions for ui5-server are now available in the form of [custom middleware extensions from the UI5-community](https://bestofui5.org/#/packages?tokens=proxy:tag). Make sure to refactor any custom middleware that attaches to `beforeMiddleware` or `afterMiddleware` of `connectUi5Proxy` to reference some other middleware. | diff --git a/examples/browsersync/README.md b/examples/browsersync/README.md index 63bffba2641..8f2040f92ac 100644 --- a/examples/browsersync/README.md +++ b/examples/browsersync/README.md @@ -1,4 +1,4 @@ -# UI5 Tooling Example - Browsersync +# UI5 CLI Example - Browsersync This example shows how to use `ui5 serve` in combination with [Browsersync](https://www.browsersync.io/) to enable live-reloading during development. diff --git a/examples/browsersync/package.json b/examples/browsersync/package.json index 327dfa50dda..5257eaaa3ff 100644 --- a/examples/browsersync/package.json +++ b/examples/browsersync/package.json @@ -1,8 +1,8 @@ { - "name": "@ui5/tooling-example-browsersync", + "name": "@ui5/cli-example-browsersync", "version": "0.0.0", "private": true, - "description": "UI5 Tooling Example - Browsersync", + "description": "UI5 CLI Example - Browsersync", "scripts": { "start": "concurrently \"npm:serve\" \"npm:browser-sync\"", "serve": "ui5 serve --port=8080", diff --git a/examples/browsersync/ui5.yaml b/examples/browsersync/ui5.yaml index 529c3eeff9f..aecb1d49cd4 100644 --- a/examples/browsersync/ui5.yaml +++ b/examples/browsersync/ui5.yaml @@ -1,4 +1,4 @@ specVersion: "1.0" metadata: - name: ui5-tooling-example-browsersync + name: ui5-cli-example-browsersync type: application diff --git a/examples/browsersync/webapp/index.html b/examples/browsersync/webapp/index.html index b951305ddd8..629850d5ce2 100644 --- a/examples/browsersync/webapp/index.html +++ b/examples/browsersync/webapp/index.html @@ -1,6 +1,6 @@ - UI5 Tooling Example - Browsersync + UI5 CLI Example - Browsersync

It works!

diff --git a/jsdoc-workspace.json b/jsdoc-workspace.json index cfe7be4c566..6a61818908e 100644 --- a/jsdoc-workspace.json +++ b/jsdoc-workspace.json @@ -29,10 +29,10 @@ } }, "openGraph": { - "title": "UI5 Tooling - API Reference", + "title": "UI5 CLI - API Reference", "type": "website", "image": "https://sap.github.io/ui5-tooling/v3/images/UI5_logo_wide.png", - "site_name": "UI5 Tooling - API Reference", + "site_name": "UI5 CLI - API Reference", "url": "https://sap.github.io/ui5-tooling/v3/" }, "docdash": { @@ -47,8 +47,8 @@ "Interfaces" ], "meta": { - "title": "UI5 Tooling - API Reference", - "description": "UI5 Tooling - API Reference", + "title": "UI5 CLI - API Reference", + "description": "UI5 CLI - API Reference", "keyword": "openui5 sapui5 ui5 build development tool api reference" }, "search": true, diff --git a/jsdoc.json b/jsdoc.json index 16855894a85..a04ec87da40 100644 --- a/jsdoc.json +++ b/jsdoc.json @@ -30,10 +30,10 @@ } }, "openGraph": { - "title": "UI5 Tooling - API Reference", + "title": "UI5 CLI - API Reference", "type": "website", "image": "https://sap.github.io/ui5-tooling/v3/images/UI5_logo_wide.png", - "site_name": "UI5 Tooling - API Reference", + "site_name": "UI5 CLI - API Reference", "url": "https://sap.github.io/ui5-tooling/v3/" }, "docdash": { @@ -48,8 +48,8 @@ "Interfaces" ], "meta": { - "title": "UI5 Tooling - API Reference", - "description": "UI5 Tooling - API Reference", + "title": "UI5 CLI - API Reference", + "description": "UI5 CLI - API Reference", "keyword": "openui5 sapui5 ui5 build development tool api reference" }, "search": true, diff --git a/lib/jsdoc/plugin/template/layout.tmpl b/lib/jsdoc/plugin/template/layout.tmpl index ef90c322385..e0e9bc0cecc 100644 --- a/lib/jsdoc/plugin/template/layout.tmpl +++ b/lib/jsdoc/plugin/template/layout.tmpl @@ -83,7 +83,7 @@