Merge pull request #454 from williamdes/more-docker

More docker + README

.github/workflows/ci.yml

@@ -151,7 +151,7 @@ jobs:
     environment:
       name: "Docker Hub"
       url: https://hub.docker.com/r/kcov/kcov
-    if: ${{ github.ref == 'refs/heads/master' }} or ${{ github.event_name == 'workflow_dispatch' }}
+    if: ${{ github.ref == 'refs/heads/master' || github.event_name == 'workflow_dispatch' }}
     steps:
     - uses: actions/checkout@v4
       with:

Dockerfile

@@ -64,6 +64,11 @@ FROM ${BUILD_OS}:${BUILD_BASE}
 ARG BUILD_OS
 ARG BUILD_BASE
 
+# For metadata
+ARG RELEASE_VERSION
+ARG VCS_REF
+ARG BUILD_DATE
+
 COPY --from=builder /usr/local/bin/kcov* /usr/local/bin/
 COPY --from=builder /usr/local/share/doc/kcov /usr/local/share/doc/kcov
 

README.md

@@ -7,7 +7,7 @@
 
 ## *kcov*
 Kcov is a FreeBSD/Linux/OSX code coverage tester for compiled languages, Python
-and Bash.  Kcov was originally a fork of [Bcov](http://bcov.sf.net), but has
+and Bash.  Kcov was originally a fork of [Bcov](https://bcov.sourceforge.net/), but has
 since evolved to support a large feature set in addition to that of Bcov.
 
 Kcov, like Bcov, uses DWARF debugging information for compiled programs to
@@ -70,19 +70,20 @@ kcov --merge /tmp/merged-output /tmp/kcov-output*    # With a wildcard
 
 Integration with other systems
 ------------------------------
-kcov is easy to integrate with [travis-ci](http://travis-ci.org) together with
-[coveralls.io](http://coveralls.io) or [codecov.io](http://codecov.io). It can also
-be used from Jenkins, [SonarQube](http://sonarqube.org) and [GitLab CI](http://gitlab.com).
+kcov is easy to integrate with [travis-ci](https://travis-ci.com/)/[GitHub actions](https://docs.github.com/en/actions) together with
+[coveralls.io](https://coveralls.io) or [codecov.io](https://codecov.io). It can also
+be used from [Jenkins](https://www.jenkins.io/), [SonarQube](https://sonarqube.org) and [GitLab CI](https://gitlab.com).
 Refer to
 
 * [vscode](doc/vscode.md) for details about vscode + coverage gutters
 * [coveralls](doc/coveralls.md) for details about travis-ci + coveralls, or
 * [codecov](doc/codecov.md) for details about travis-ci + codecov
 * [jenkins](doc/jenkins.md) for details about how to integrate in Jenkins
 * [sonarqube](doc/sonarqube.md) for how to use kcov and sonarqube together
+* [GitHub](doc/github.md) for use with GitHub
 * [gitlab](doc/gitlab.md) for use with GitLab
 
 More information
 ----------------
 kcov is written by Simon Kagstrom <simon.kagstrom@gmail.com> and more
-information can be found at [the web page](http://simonkagstrom.github.io/kcov/index.html)
+information can be found at [the web page](https://simonkagstrom.github.io/kcov/index.html)

doc/docker.md

@@ -14,3 +14,80 @@ kcov needs access the following system calls:
 - [`personality`](https://linux.die.net/man/2/personality)
 
 You may need to use `--security-opt seccomp=unconfined` as a docker run option to attach to processes.
+
+## Copy into your image
+
+You may want to copy kcov into your image to avoid building it.
+
+```Dockerfile
+# Copy kcov (use kcov/kcov:latest-alpine for Alpine based images)
+COPY --from=kcov/kcov:latest /usr/local/bin/kcov* /usr/local/bin/
+# If you need documentation
+COPY --from=kcov/kcov:latest /usr/local/share/doc/kcov /usr/local/share/doc/kcov
+```
+
+### Python + bats example
+
+```Dockerfile
+# The base layer of your image
+FROM python:3.11-slim-bookworm
+
+# Install kcov run-time dependencies and bats.
+RUN apt-get update && \
+    apt-get install --yes --no-install-suggests --no-install-recommends \
+      libbfd-dev \
+      libcurl4 \
+      libdw1 \
+      zlib1g \
+      bats \
+      && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy kcov (use kcov/kcov:latest-alpine for Alpine based images)
+COPY --from=kcov/kcov:latest /usr/local/bin/kcov* /usr/local/bin/
+COPY --from=kcov/kcov:latest /usr/local/share/doc/kcov /usr/local/share/doc/kcov
+
+WORKDIR /code
+
+CMD ["bats"]
+```
+
+#### Test it
+
+##### `test.sh`
+
+```sh
+#!/usr/bin/env bats
+
+source script.sh
+
+@test "test outputNumber function" {
+  result="$( outputNumber )"
+  [ "$result" -eq 7 ]
+}
+
+@test "kcov version" {
+  kcov --version | grep -q -c -F "v"
+  [ "$?" -eq 0 ]
+}
+```
+
+##### `script.sh`
+
+```sh
+outputNumber() {
+  echo 7
+}
+```
+
+##### Run tests
+
+```sh
+# build our image
+docker build ./ -t py-bats
+# test the built image
+docker run --rm -it -v $PWD:/code py-bats kcov --include-path=/code --dump-summary ./coverage bats ./test.sh
+# See the coverage result in ./coverage
+# Browse the file coverage/index.html in your browser
+```

doc/github.md

@@ -0,0 +1,68 @@
+# GitHub actions
+
+## Example usage
+
+### `bash-script.sh`
+
+```sh
+#!/usr/bin/env bash
+
+if [[ true ]]; then
+  echo "Hello, kcov!"
+fi
+```
+
+### `tests.sh`
+
+```sh
+#!/bin/sh
+
+testEquality() {
+  assertEquals 1 1
+}
+
+. shunit2
+```
+
+### `.github/workflows/tests.yml`
+
+```yml
+name: Run tests
+
+permissions:
+  contents: read
+
+on: [push]
+
+jobs:
+  tests:
+    name: Run tests
+    runs-on: ubuntu-latest
+    steps:
+        - uses: actions/checkout@v4
+
+        - name: Example with a bash script (running on Docker kcov/kcov)
+          uses: sudo-bot/action-kcov@latest
+          with:
+            cli-args: "--version"
+
+        - name: Run a bash script with kcov coverage
+          # Debian based, uses the Docker image kcov/kcov
+          uses: sudo-bot/action-kcov@latest
+          with:
+            cli-args: "--dump-summary ./coverage ./bash-script.sh"
+
+        - name: Run shunit2 tests with kcov coverage
+          # Alpine based
+          uses: sudo-bot/action-shunit2@latest
+          with:
+              cli: "kcov --dump-summary ./coverage ./tests.sh"
+
+        - name: Upload coverage reports to Codecov
+          uses: codecov/codecov-action@v4
+          with:
+            # Must be set in the repo or org settings as a secret
+            token: ${{ secrets.CODECOV_TOKEN }}
+            directory: ./coverage/
+            fail_ci_if_error: true
+```