diff --git a/internal/documentation/docs/pages/Builder.md b/internal/documentation/docs/pages/Builder.md index 2bf7a74fa46..e314866932d 100644 --- a/internal/documentation/docs/pages/Builder.md +++ b/internal/documentation/docs/pages/Builder.md @@ -199,3 +199,30 @@ sap.ui.define([], () => { text-decoration: inherit; } + +## Build Cache Control + +The UI5 Builder integrates **build caches**. Instead of rebuilding everything from scratch, the UI5 Builder tracks which resources have changed and which build tasks need to be re-executed: + +You can control the build cache behavior using the `--cache` option: + +- `--cache Default` (default): Use the cache if available, create it if missing +- `--cache Force`: Only use the cache; fail if the cache is unavailable or invalid +- `--cache ReadOnly`: Use existing cache but don't update it (useful for CI/CD) +- `--cache Off`: Disable caching entirely and always perform a full rebuild + +Example: +```sh +ui5 build --cache Off +``` +In this scenario, when a source file change is made, always perform a full rebuild (even if this source version already existed sometime ago). + +::: info +By default, the build cache is stored inside UI5 CLI's Data Dir (`~/.ui5/buildCache/`). You can customize the location (see [Changing UI5 CLI's Data Directory](./Troubleshooting#changing-ui5-cli-s-data-directory)). +::: + +::: info +Build caches created by `ui5 build` and `ui5 serve` are **separate and cannot be mixed**. Each command maintains its own cache optimized for its specific use case. For more details on server caching, see the [UI5 Server documentation](./Server.md). +::: + + diff --git a/internal/documentation/docs/pages/Server.md b/internal/documentation/docs/pages/Server.md index 64fd885fe4a..31b36fb6bb6 100644 --- a/internal/documentation/docs/pages/Server.md +++ b/internal/documentation/docs/pages/Server.md @@ -87,6 +87,49 @@ Answers all non-read requests (POST, PUT, DELETE, etc.) that have not been answe ### serveIndex In case a directory has been requested, this middleware renders an HTML with a list of the directory's content. +## Standard Tasks +As with the UI5 Builder, a set of standard tasks is being executed during a server build. However, following tasks are being **excluded by default**: +- `minify` +- `generateLibraryPreload` +- `generateComponentPreload` +- `generateBundle` + +::: info +See [Builder Standard Tasks](./Builder.md#standard-tasks) for more explanation about each task. +::: + +## Build Cache Control + +The UI5 Server performs a build of the projects by utilizing **build caches**. + +You can control the build cache behavior using the `--cache` option: + +- `--cache Default` (default): Use the cache if available, create it if missing +- `--cache Force`: Only use the cache; fail if the cache is unavailable or invalid +- `--cache ReadOnly`: Use existing cache but don't update it (useful for CI/CD) +- `--cache Off`: Disable caching entirely and always perform a full rebuild + +Example: +```sh +ui5 serve --cache Off +``` +In this scenario, when a source file change is made and a request comes in, the server always performs a full rebuild (even if this source version already existed sometime ago). + +::: info +Build caches created by `ui5 build` and `ui5 serve` are **separate and cannot be mixed**. Each command maintains its own cache optimized for its specific use case. For more details on builder caching, see the [UI5 Builder documentation](./Builder.md). +::: + +### Watch Mode Behavior + +Once started with `ui5 serve`, the server automatically keeps watch over changes to the source files throughout the session. When a request arrives, it checks for cached results first and only triggers a rebuild of the respective resources and tasks if no cache is available. + +- **Monitored files**: All files in your project's source directories (`src/`, `webapp/`, `test/`, etc.) +- **Not monitored**: Configuration files (`ui5.yaml`, `package.json`), custom task implementations, and dependency files + +::: info +Changes to configuration files or custom tasks require a server restart to take effect. +::: + ## SSL Certificates When starting the UI5 Server in HTTPS- or HTTP/2 mode, for example by using UI5 CLI parameter `--h2`, you will be prompted for the automatic generation of a local SSL certificate if necessary. diff --git a/internal/documentation/docs/pages/extensibility/CustomTasks.md b/internal/documentation/docs/pages/extensibility/CustomTasks.md index 23c27aa1c76..33a67d0f910 100644 --- a/internal/documentation/docs/pages/extensibility/CustomTasks.md +++ b/internal/documentation/docs/pages/extensibility/CustomTasks.md @@ -286,11 +286,37 @@ module.exports.determineRequiredDependencies = async function({availableDependen ``` ::: +### "Cache-aware" Tasks + +Due to UI5 Builder and UI5 Server supporting **build caches** of task data, custom tasks can opt into this behavior to improve performance. This is done by implementing the following features: + +#### `supportsDifferentialBuilds()` + +This method indicates whether your task can perform differential builds: + +```js +/** + * Indicates whether this task can perform differential builds + * + * @returns {boolean} True if the task can process only modified resources + */ +export function supportsDifferentialBuilds() { + return true; +} +``` + +When this returns `true`, your task's main function receives an additional parameter indicating which resources have changed. The task can then process only those resources instead of all resources. + +::: info Best Practices for Cache-aware Tasks +1. **Keep tasks deterministic**: Given the same inputs, always produce the same outputs +2. **Opt into differential builds carefully**: Only set `supportsDifferentialBuilds = true` if your task can safely process files independently +::: + ### Examples The following code snippets show examples for custom task implementations. -### Example: lib/tasks/renderMarkdownFiles.js +#### Example: lib/tasks/renderMarkdownFiles.js This example is making use of the `resourceFactory` [TaskUtil](https://ui5.github.io/cli/v5/api/@ui5_project_build_helpers_TaskUtil.html) API to create new resources based on the output of a third-party module for rendering Markdown files. The created resources are added to the build @@ -364,7 +390,7 @@ Tasks should ideally use the reader/writer APIs provided by UI5 CLI for working ::: -### Example: lib/tasks/compileLicenseSummary.js +#### Example: lib/tasks/compileLicenseSummary.js This example is making use of multiple [TaskUtil](https://ui5.github.io/cli/v5/api/@ui5_project_build_helpers_TaskUtil.html) APIs to retrieve additional information about the project currently being built (`taskUtil.getProject()`) and its direct dependencies diff --git a/internal/documentation/docs/updates/migrate-v5.md b/internal/documentation/docs/updates/migrate-v5.md index 1612bd6dfa9..bcb8d74ceb3 100644 --- a/internal/documentation/docs/updates/migrate-v5.md +++ b/internal/documentation/docs/updates/migrate-v5.md @@ -29,6 +29,47 @@ UI5 CLI 5.x introduces **Specification Version 5.0**, which enables the new Comp Projects using older **Specification Versions** are expected to be **fully compatible with UI5 CLI v5**. +## Build Cache + +UI5 CLI v5 introduces **builds with caching** for both commands `ui5 build` and `ui5 serve`. This fundamental architectural change significantly improves build performance by reusing cached results from previous builds. + +### What Changed + +**Previous Behavior (v4 and earlier):** +- Every source change resulted in an entire rebuild of all projects +- Every build re-executed all tasks +- No caching between builds or server sessions + +**New Behavior (v5):** +- Only relevant projects are rebuilt +- Only modified resources and affected tasks are re-processed + +### Impact on Your Workflow + +- **First build**: Probably slightly slower, as the cache is populated with all build outputs +- **Subsequent builds**: Significantly faster — only modified resources and affected tasks are reprocessed +- **Quick iterations**: Changes to individual files typically rebuild very quickly +- **Cross-session**: Caches are used between server restarts and build runs + +### For `ui5 build` + +When `ui5 build` is executed, build caches are automatically serialized and reused when available. + +::: tip Tip for Single Builds (e.g. CI/CD) +If you plan to execute a build only once (e.g. during a CI run), consider using `--cache "Off"` (see [Build Cache Control](../pages/Builder.md#build-cache-control)) to skip cache serialization. +::: + +### For `ui5 serve` + +During a server session (started by `ui5 serve`), source changes are automatically being monitered. Then, if a request was made, the server detects this, tries to use caches and only rebuilds when none are available. For more information see [Watch Mode Behavior](../pages/Server.md#watch-mode-behavior). + +::: info Review custom middleware + +With this feature, **build tasks are executed in server sessions**. For this reason, some custom middleware might be obsolete or cause problems. Projects utilizing such might need to adapt their configuration. + +E.g. Middleware for browser live reloads is obsolete and can be removed. Also, middleware for Typescript transpilation is not required anymore (as long as the respective task is still set up). +::: + ## Rename of Command Option With UI5 CLI v5, the option `--cache-mode` (for commands `ui5 build` and `ui5 serve`) has been renamed to `--snapshot-cache`.