commandunit is developed on Linux Platform (Ubuntu22.04)

Requirements

build.sh

Building, testing, generating doc, and releasing can be done with a script build.sh. It takes an array of subcommands. Subcommands can be classified into two groups, which are "grouped subcommands" and "basic subcommands". A "grouped subcommand" is interpreted as a sequence of subcommands and executed by build.sh one by one.

If you don’t specify any subcommand:

$ ./build.sh

It will be interpreted that BUILD grouped subcommand is specified.

Basic Subcommands

Parameters

A basic subcommand can take parameters. There are three targets: source, snapshot, and release. source means that the subcommand handles source files. For instance, if the target is source, the test subcommand uses source files for test. If it is snapshot, a snapshot docker image will be used. If release, a docker image to be released will be used.

build

Builds a docker image from a source.

Only snapshot and release can be specified for the first parameter.

clean

Removes all the working files generated by this build script. Note that files created by generate-src will not be removed since they are a part of the source tree, not working files.

This subcommand doesn’t take any parameters.

dummy

This subcommand does nothing. Useful for testing a change made in build.sh.

This subcommand doesn’t take any parameters.

fail

This subcommand fails always. Useful for testing a change made in build.sh.

This subcommand doesn’t take any parameters.

coverage

This command executes test and generates a coverage report. Generated coverage report will be found under out/testreport-coverage directory.

This subcommand doesn’t take any parameters.

doc

Generates documentation under working directory from asciidoc (.adoc) files under OUTDIR/site/adoc directory, whose contents are copied from src/site/adoc directory. The generated documentation (.html files) will be found under OUTDIR/doc directory.

This subcommand doesn’t take any parameters.

generate-src

A subcommand to generate "source" files based on project information such as the current target development version, repository URL, etc. Typically executed at the last of RELEASE subcommand.

This subcommand doesn’t take any parameters.

prepare

Copies the source tree (SRCDIR) to the working directory (OUTDIR).

This subcommand doesn’t take any parameters.

publish-doc

Pushes the generated documents to a branch of the git repository, the branch (.repo.documentation.docbranch attribute) and repository URL (.repo.url attribute) can be specified in build_info.json.

This subcommand doesn’t take any parameters.

push

Pushes a docker image to the docker repository.

The first parameter specifies snapshot or released image to be pushed.

test

Executes unit test suites stored under out/test/scripts.

The first parameter specifies the type of the commandunit executable used for the test execution. source means the scripts before dockerized, snapshot is a docker image for snapshot, and release is a docker image to be released.

release-precheck

Performs a "pre-check" for the entire release procedure. It checks if there is no uncommitted changes, un-pushed commits, and you are on the main branch.

release-postmortem

Some files in the source tree of commandunit should be generated in an automated way, otherwise they will become redundant.

Grouped Subcommands

Grouped subcommands do not take any parameters.

BUILD

A basic "build" command. It generates documentation and execute tests.

$ ./build.sh BUILD
Included Subcommands

clean, prepare, doc, and test

DOC

$ ./build.sh DOC

A subcommand to build documentation under working directory. Generated HTML files will be found under out/doc directory.

Included Subcommands

clean, prepare, and doc

TEST

$ ./build.sh TEST

Executes the test suite.

Included Subcommands

clean, prepare, and test

COVERAGE

$ ./build.sh COVERAGE
Included Subcommands

clean, prepare, and coverage

PACKAGE

$ ./build.sh PACKAGE
Included Subcommands

clean prepare, test:::true, build:snapshot, and test:snapshot::true

DEPLOY

$ ./build.sh DEPLOY
Included Subcommands

PACKAGE and push:snapshot

RELEASE

$ ./build.sh RELEASE

A subcommand for releasing. Note that a check will be done at the beginning of this subcommand. If something not pushed on your local, this subcommand fails (release-precheck). Also, note that documentation is not published by this subcommand, and you need to do it separately using PUBLISH_DOC subcommand.

Included Subcommands

clean, release-precheck, prepare, test:::true, build:release, test:release::true, push:release, and release-postmortem.

PUBLISH_DOC

$ ./build.sh PUBLISH_DOC

Repository

The source code repository of commandunit is found here.

Tags

Each released commit has a tag: v{Major Version}.{Minor Version}. For the commit whose "wrapper script" was verified most recently has a tag wrapper-verified.

Branches

The documentation is stored in docs branch and exposed to the public through dakusui.github.io/commandunit. Check also PUBLISH_DOC subcommand of the build script.

Directory Structure

PROJECT_BASEDIR/                                      (1)
  buildtools/          A directory for build tools.
  out/                 A directory for working files. (2)
    doc/                                              (3)
    main/
      scripts/                                        (4)
    site/
      adoc/                                           (5)
  src/                 A directory for source tree    (6)
    docker/
    main/
    site/
    test/
  build.sh             A build script for this project.
  build_info.json      A project definition file.

  • <1>: project base directory.

  • <2>: Specified by environment variable OUTDIR.

  • <3>: DOCDIR.

  • <4>: EXEC_BASEDIR.

  • <5>: DOC_SRCDIR.

  • <6>: Specified by environment variable SRCDIR.

build_info.json

build_info.json example
{
  "projectName": "commandunit",
  "homepage": "https://github.com/dakusui/commandunit",
  "docker": {
    "user": "dakusui",
    "hostFsRootMountPoint": "/var/lib/commandunit"
  },
  "version": {
    "latestReleased": {
      "major": 1,
      "minor": 25
    },
    "target": {
      "major": 1,
      "minor": 26
    }
  },
  "repo": {
    "url": "https://github.com/dakusui/commandunit.git",
    "documentation": {
      "docbranch": "docs"
    },
    "release": {
      "branch": "main"
    }
  }
}

Build-time Environment Variables

LATEST_RELEASED_VERSION

The most recent released version of this product.

TARGET_VERSION

The version currently under development.

PROJECT_NAME

The name of this project.

PROJECT_BASEDIR

The path to the root directory of this project.

HOMEPAGE

The URL of the project’s homepage.

SRCDIR

The path to the source directory (i.e., ${PROJECT_BASEDIR}/src) OUTDIR: The path to the working directory (i.e., ${PROJECT_BASEDIR}/out)

EXEC_BASEDIR

The directory that holds executables of this product during the build-time. (i.e., ${PROJECT_BASEDIR}/out/main/scripts)

DOCDIR

The directory to store generated documentations. (i.e., ${PROJECT_BASEDIR}/out/doc)

DOCSRCDIR

The directory to store documentation source files during a build. (i.e., ${PROJECT_BASEDIR}/out/doc)

DOCKER_REPO_NAME

A name of docker repository name. (i.e., {.docker.user}/{.project.name}).

BUILD_HOSTFSROOT_MOUNTPOINT

A path under which the root directory of the host side file system "seems" mounted. By prefixing this path to a host side path, you can calculate the corresponding path of it inside the docker container.

Known Problems

  • A build on macOS halts during test.