From ebcb22a462cdb4502b8a754aab8c83f9ab1817d8 Mon Sep 17 00:00:00 2001 From: Markus Ofterdinger Date: Tue, 17 Dec 2024 16:36:45 +0100 Subject: [PATCH] Update installation of local cds-dk (#1510) BLI: https://github.wdf.sap.corp/cds-java/home/issues/1859 --------- Co-authored-by: Mahati Shankar <93712176+smahati@users.noreply.github.com> Co-authored-by: BraunMatthias <59841349+BraunMatthias@users.noreply.github.com> Co-authored-by: Mahati Shankar --- java/developing-applications/building.md | 84 ++++++++++++++++++++---- 1 file changed, 71 insertions(+), 13 deletions(-) diff --git a/java/developing-applications/building.md b/java/developing-applications/building.md index c3131f6c5..c9a0a5e8a 100644 --- a/java/developing-applications/building.md +++ b/java/developing-applications/building.md @@ -377,27 +377,85 @@ Use the _.cdsrc.json_ file to add project specific configuration of `@sap/cds-dk ### Using a Local cds-dk -By default, the build is configured to download a Node.js runtime and the `@sap/cds-dk` tools and install them locally within the project. -The `install-cdsdk` goal requires a version of `@sap/cds-dk`, which [needs to be provided explicitly](../../releases/archive/2022/oct22#important-changes-in-java) in the configuration. With this, you can ensure that the build is fully reproducible. -You can provide this version by adding the following property to the `properties` section in your `pom.xml`: - -```xml - - ... - FIXED VERSION - +Starting with version 3.6.0 of the `cds-services-archetype`, the default setup of a newly created CAP Java project has changed. The `@sap/cds-dk` is maintained as a `devDependency` in `package.json` and installed with an `npm ci` during the Maven build. +The `install-cdsdk` goal is no longer used to install the `@sap/cds-dk` locally and it's also marked as deprecated. The version of the `@sap/cds-dk` is no longer maintained in `pom.xml`, it's configured in the `package.json`: +```json +{ + "devDependencies" : { + "@sap/cds-dk" : "^8.5.1", + } +} ``` +A `package-lock.json` is also created during project creation with the `cds-services-archetype`. The lock file is needed for `npm ci` to run successfully and pins the transitive dependencies of @sap/cds-dk to fixed versions. Fixing the versions ensures that the CDS build is fully reproducible. ::: warning -Make sure to regularly update `@sap/cds-dk` according to [our guidance](../../releases/schedule). - For multitenant applications, ensure that the `@sap/cds-dk` version in the sidecar is in sync. ::: +#### Migrate from goal `install-cdsdk` to `npm ci` { #migration-install-cdsdk } + +To migrate from the deprecated goal `install-cdsdk` to the new `npm ci` approach, the following steps are required: + +1. Remove execution of goal `install-cdsdk` from the `cds-maven-plugin` in `srv/pom.xml`: +```xml + + com.sap.cds + cds-maven-plugin + ${cds.services.version} + + + + cds.install-cdsdk + + install-cdsdk + + + +``` + +2. Then add execution of goal `npm` with arguments `ci` instead to the `cds-maven-plugion` in `srv/pom.xml`: +```xml + + cds.npm-ci + + npm + + + ci + + +``` + +3. Remove cds-dk version property `cds.install-cdsdk.version` from `pom.xml`: +```xml + + + 8.4.2 + + +``` + +4. Add `@sap/cds-dk` as devDependency to `package.json`: +```json +{ + "devDependencies" : { + "@sap/cds-dk" : "^8.5.0" + } +} +``` + +5. Perform `npm install` on the command line to get the `package-lock.json` created or updated. + +6. Finally, do a `mvn clean install` and verify that the installation of `@sap/cds-dk` is done with the new approach. + #### Maintaining cds-dk -By default, the goal `install-cdsdk` of the `cds-maven-plugin` skips the installation of the `@sap/cds-dk`, if the `@sap/cds-dk` is already installed. -To update the `@sap/cds-dk` version in your application project do the following: +1. package.json and npm ci +Newly created CAP Java projects maintain the `@sap/cds-dk` with a specific version as a devDependency in `package.json`. So, when you update the version, run npm install from the command line to update the `package-lock.json`. `npm ci` will then install the updated version of `@sap/cds-dk`. + +2. Goal install-cdsdk + Older CAP Java projects that use the `install-cdsdk` goal of the `cds-maven-plugin` don't update `@sap/cds-dk`. By default, the goal skips the installation if it's already installed. +To update the `@sap/cds-dk` version: 1. Specify a newer version of `@sap/cds-dk` in your *pom.xml* file. 2. Execute `mvn spring-boot:run` with an additional property `-Dcds.install-cdsdk.force=true`, to force the installation of a **`@sap/cds-dk`** in the configured version.