Skip to content

Commit

Permalink
Render docs and tasks
Browse files Browse the repository at this point in the history
  • Loading branch information
@michaelsauter
michaelsauter committed Sep 22, 2023
1 parent f3fc84d commit 6208caf
Show file tree
Hide file tree
Showing 2 changed files with 93 additions and 81 deletions.
78 changes: 40 additions & 38 deletions docs/build.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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

|===

Expand Down
96 changes: 53 additions & 43 deletions tasks/build.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -16,97 +16,107 @@ 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
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.
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<xx>-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
copy-artifacts --debug=${DEBUG}
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
Expand Down

0 comments on commit 6208caf

Please sign in to comment.