diff --git a/docs/build.adoc b/docs/build.adoc index 53a2396..04ef50f 100644 --- a/docs/build.adoc +++ b/docs/build.adoc @@ -2,28 +2,40 @@ = ods-pipeline-npm-build -Builds Go applications. +Builds Node.js applications using npm. + +The built-in script executes the following steps: + +- check that package.json and package-lock.json exist to require best practice of using lock files. See also link:https://github.com/opendevstack/ods-pipeline/discussions/411[discussion 411] +- linting using `npm run lint` +- build application, using `npm run build` +- test execution, using `npm run test` + +For linting to work there needs to be a `lint` task in the `package.json` file, +for example `npx eslint src --format compact`, together with a config file +(`eslintrc.json` or similar) at the root of the working directory. This can +be done by running `eslint --init` or by following the +link:https://eslint.org/docs/user-guide/getting-started[official documentation]. The exact build recipe can be found at -link:https://github.com/opendevstack/ods-pipeline-npm/blob/main/build/images/scripts/build.sh[build/images/scripts/build.sh]. +link:https://github.com/opendevstack/ods-pipeline/blob/master/build/package/scripts/build-npm.sh[build/package/scripts/build-npm.sh]. +In particular, `npm run build` is expected to place outputs into `dist` and +`npm run test` is expected to create `build/test-results/test/report.xml` +and `build/coverage/{clover.xml,coverage-final.json,lcov.info}`. -The following provides an overview of the performed steps: +An example configuration for the test script is: -- Source files are checked to be formatted with `gofmt`. -- The go module cache is configured to be on the cache location of the PVC by setting environment variable `GOMODCACHE` to `.ods-cache/deps/gomod` (see link:https://go.dev/ref/mod#module-cache[go module cache]). -- `golanci-lint` is run. The linter can be configured via a - config file as described in the - link:https://golangci-lint.run/usage/configuration/[configuration documentation]. -- Tests are executed. A potential `vendor` directory is excluded. Test - results are converted into xUnit format. -- Application binary (named `app`) is built and placed into the directory - specified by `output-dir`. +``` +JEST_JUNIT_OUTPUT_DIR='build/test-results/test' JEST_JUNIT_OUTPUT_NAME='report.xml' npx jest --reporters=default --reporters=jest-junit --coverage --coverageDirectory=build/coverage --forceExit ./dist +``` The following artifacts are generated by the build task and placed into `.ods/artifacts/` * `code-coverage/` - ** `coverage.out` -* `lint-reports/` + ** `clover.xml` + ** `coverage-final.json` + ** `lcov.info` +* `lint-reports` ** `report.txt` * `xunit-reports/` ** `report.xml` @@ -50,39 +62,29 @@ without leading `./` and trailing `/`. -| enable-cgo -| false -| Whether to enable CGO. When not enabled the build will set `CGO_ENABLED=0`. - - -| go-os -| linux -| `GOOS` variable (the execution operating system such as `linux`, `windows`). - - -| go-arch -| amd64 -| `GOARCH` variable (the execution architecture such as `arm`, `amd64`). +| cache-build +| true +| If enabled tasks uses or populates cache with the output dir contents (and artifacts) so that a build can be skipped if the `working-dir` contents did not change. You must set this to `"false"` if the build can be affected by files outside `working-dir`. See ADR caching-build-tasks for more details and workarounds. -| output-dir -| docker -| Path to the directory into which the resulting Go binary should be copied, relative to `working-dir`. This directory may then later be used as Docker context for example. +| build-extra-inputs +| +| List of build source directories (as colon separated string) which in addition working-dir influence the build. These directories are relative to the repository root. If the contents in these directories change the cache is invalidated so that the build task will rebuild from scratch. -| cache-build -| true -| If enabled tasks uses or populates cache with the output dir contents (and artifacts) so that a build can be skipped if the `working-dir` contents did not change. You must set this to `"false"` if the build can be affected by files outside `working-dir`. See ADR caching-build-tasks for more details and workarounds. +| cached-outputs +| dist +| List of build output directories (as colon separated string) to be cached. These directories are relative to the `working-dir` parameter` Common build directories are `dist` (default), `build` and `public`. If empty this could mean that the original sources are being used as build output and no caching of built files are needed. Nonetheless build skipping can still be remain enabled. | build-script -| /usr/local/bin/go-build -| Build script to execute. The link:https://github.com/opendevstack/ods-pipeline-npm/blob/main/build/images/scripts/go-build.sh[default script] is located in the container image. If you specify a relative path instead, it will be resolved from the workspace. See the task definition for details how the build script is invoked. +| /usr/local/bin/build-npm +| Build script to execute. The link:https://github.com/opendevstack/ods-pipeline/blob/master/build/package/scripts/build-npm.sh[default script] is located in the container image. If you specify a relative path instead, it will be resolved from the workspace. See the task definition for details how the build script is invoked. -| pre-test-script -| -| Script to execute before running tests, relative to the working directory. +| node-version +| 18 +| Node.js version to use - supported versions: 16, 18 |=== diff --git a/tasks/build.yaml b/tasks/build.yaml index c3acbd2..6c15d3d 100644 --- a/tasks/build.yaml +++ b/tasks/build.yaml @@ -6,7 +6,7 @@ metadata: name: ods-pipeline-npm-build spec: description: | - Builds Go applications. + Builds NPM applications. See https://github.com/opendevstack/ods-pipeline-npm/blob/vlatest/docs/build.adoc params: @@ -16,24 +16,6 @@ spec: without leading `./` and trailing `/`. type: string default: "." - - name: enable-cgo - description: Whether to enable CGO. When not enabled the build will set `CGO_ENABLED=0`. - type: string - default: "false" - - name: go-os - description: "`GOOS` variable (the execution operating system such as `linux`, `windows`)." - type: string - default: "linux" - - name: go-arch - description: "`GOARCH` variable (the execution architecture such as `arm`, `amd64`)." - type: string - default: "amd64" - - name: output-dir - description: >- - Path to the directory into which the resulting Go binary should be copied, relative to `working-dir`. - This directory may then later be used as Docker context for example. - type: string - default: docker - name: cache-build description: >- If enabled tasks uses or populates cache with the output dir contents (and artifacts) so that @@ -41,57 +23,85 @@ spec: You must set this to `"false"` if the build can be affected by files outside `working-dir`. See ADR caching-build-tasks for more details and workarounds. type: string default: "true" + - name: build-extra-inputs + description: >- + List of build source directories (as colon separated string) which in addition working-dir influence the build. + These directories are relative to the repository root. + If the contents in these directories change the cache is invalidated so that the build task will rebuild from scratch. + type: string + default: "" + - name: cached-outputs + description: >- + List of build output directories (as colon separated string) to be cached. + These directories are relative to the `working-dir` parameter` + Common build directories are `dist` (default), `build` and `public`. + If empty this could mean that the original sources are being used as build output and no caching of built files are needed. Nonetheless build skipping can still be remain enabled. + type: string + default: "dist" - name: build-script description: >- Build script to execute. The - link:https://github.com/opendevstack/ods-pipeline-npm/blob/main/build/images/scripts/go-build.sh[default script] + link:https://github.com/opendevstack/ods-pipeline/blob/master/build/package/scripts/build-npm.sh[default script] is located in the container image. If you specify a relative path instead, it will be resolved from the workspace. See the task definition for details how the build script is invoked. type: string - default: "/usr/local/bin/go-build" - - name: pre-test-script - description: Script to execute before running tests, relative to the working directory. + default: "/usr/local/bin/build-npm" + - name: node-version + description: "Node.js version to use - supported versions: 16, 18" type: string - default: "" + default: "18" results: - description: The cache location that the build task used. If caching is not enabled this will be an empty string. name: build-reused-from-location steps: - - name: go-build - # Image is built from build/images/Dockerfile.node18-npm-toolset. - image: 'ghcr.io/opendevstack/ods-pipeline-npm/node18-npm-toolset:latest' + - name: build-npm + # Image is built from build/package/Dockerfile.node-npm-toolset. + image: 'ghcr.io/opendevstack/ods-pipeline-npm/node$(params.node-version)-npm-toolset:latest' env: - name: HOME value: '/tekton/home' - name: CI value: "true" + - name: NEXUS_URL + valueFrom: + configMapKeyRef: + key: url + name: ods-nexus + - name: NEXUS_USERNAME + valueFrom: + secretKeyRef: + key: username + name: ods-nexus-auth + - name: NEXUS_PASSWORD + valueFrom: + secretKeyRef: + key: password + name: ods-nexus-auth - name: DEBUG valueFrom: configMapKeyRef: key: debug name: ods-pipeline + resources: + {} script: | echo -n "" > $(results.build-reused-from-location.path) - cache_build_key=go-$(params.go-os)-$(params.go-arch) + cache_build_key=npm if copy-build-if-cached \ --cache-build=$(params.cache-build) \ --cache-build-key="$cache_build_key" \ + --build-extra-inputs=$(params.build-extra-inputs) \ + --cached-outputs=$(params.cached-outputs) \ --cache-location-used-path=$(results.build-reused-from-location.path) \ --working-dir=$(params.working-dir) \ - --output-dir=$(params.output-dir) \ --debug=${DEBUG} ; then exit 0 fi - # Default build script is build/images/scripts/go-build.sh. + # Default build script is build/package/scripts/build-npm.sh. set +e $(params.build-script) \ --working-dir=$(params.working-dir) \ - --enable-cgo=$(params.enable-cgo) \ - --go-os=$(params.go-os) \ - --go-arch=$(params.go-arch) \ - --pre-test-script=$(params.pre-test-script) \ - --output-dir=$(params.output-dir) \ --debug=${DEBUG} build_exit=$? set -e @@ -99,14 +109,14 @@ spec: if [ $build_exit -ne 0 ]; then exit $build_exit fi - if [ "$(params.cache-build)" == "true" ]; then - cache-build \ - --cache-build-key="$cache_build_key" \ - --cache-location-used-path=$(results.build-reused-from-location.path) \ - --working-dir=$(params.working-dir) \ - --output-dir=$(params.output-dir) \ - --debug=${DEBUG} - fi + cache-build \ + --cache-build=$(params.cache-build) \ + --cache-build-key="$cache_build_key" \ + --build-extra-inputs=$(params.build-extra-inputs) \ + --cached-outputs=$(params.cached-outputs) \ + --cache-location-used-path=$(results.build-reused-from-location.path) \ + --working-dir=$(params.working-dir) \ + --debug=${DEBUG} volumeMounts: - mountPath: /etc/ssl/certs/private-cert.pem name: private-cert