cqfd provides a quick and convenient way to run commands in the current directory, but within a Docker container defined in a per-project config file. This becomes useful when building an application designed for another Linux system, e.g. building a RHEL7 app when your workstation runs on Ubuntu 16.04.
To use cqfd, ensure the following requirements are satisfied on your workstation:
-
Bash 4.x
-
Docker
-
A
dockergroup in your /etc/group -
Your username is a member of the
dockergroup -
Restart your docker service if you needed to create the group.
The cqfd script can be installed system-wide.
Install or remove the script and its resources:
$ make install
$ make DESTDIR=/usr install
$ make uninstall
The .cqfdrc file at the root of your project contains the information required to support project tooling. samples/dot-cqfdrc is an example.
Here is a sample .cqfdrc file:
[project]
org='fooinc'
name='buildroot'
[build]
command='make foobar_defconfig && make && asciidoc README.FOOINC'
[release]
files='README.FOOINC output/images/sdcard.img'
Build flavors
In some cases, it may be desirable to build the project using variations of the build and release methods. This is made possible in cqfd with the build flavors feature.
In the .cqfdrc file, flavors may be listed in the build section,
referencing sections prefixed with the flavor’s name.
[foo]
command='make foobar_foo_defconfig && make && asciidoc README.FOOINC'
files='README.FOOINC output/images/sdcard_foo.img'
[bar]
command='make foobar_bar_defconfig && make && asciidoc README.FOOINC'
files='README.FOOINC output/images/sdcard_bar.img'
[build]
flavors='foo bar'
Section project
project.org This is a short, lowercase name for the project’s parent organization. This name will be used in gerrit to prefix the repository paths, in docker to prefix the image names, and in various other places.
project.name This is a short, lowercase name for the project, used in
gerrit as the repository name, for example buildroot or linux.
Section build
build.command The command (or list of commands). This string will be
passed as an argument to a classical bash -c "commands", within the
build container, to generate the build artefacts.
build.flavors List of build flavors. Each flavor has its own command just like build.command.
Section release
release.files A space-separated list of files generated by the build process that we want to include inside a standard release archive.
Section flavor
flavor.command The equivalent of build.command for a given flavor.
flavor.files The equivalent of release.files for a given flavor.
Environment variables
The following environment variables are supported by cqfd to provide
the user with extra flexibility during his day-to-day development tasks:
CQFD_EXTRA_VOLUMES: A space-separated list of additional volume mappings to be configured inside the started container. Format is the same as docker-run’s -v option.
Enter your project repository and grab the provided sample files:
$ cd path/to/fooinc/barproject/
$ cp <cqfd_source_dir>/samples/dot-cqfdrc ./.cqfdrc
$ mkdir -p ./.cqfd/docker
$ cp <cqfd_source_dir>/samples/Dockerfile.trusty.nodejs5x \
./.cqfd/docker/Dockerfile
Once the initial configuration has been done, the cqfd helper script
can be used to automate the generation of the build container, as well
as executing your build commands inside the container.
The following command creates the initial build container:
$ cqfd init
cqfd will use the provided Dockerfile (which must be located in the
.cqfd/docker/ directory of your project) to create a normalized runtime
build environment for your project.
Regular builds
To build your project from the configured build environment with the default build command as configured in .cqfdrc, use:
$ cqfd
Alternatively, you may want to specify a custom build command to be executed from inside the build container.
$ cqfd run make clean
$ cqfd run "make linux-dirclean && make foobar-dirclean"
When cqfd is running, the current directory is mounted by Docker as
a volume. As a result, all the build artefacts generated inside the
container are still accessible in this directory.
Release
The release command behaves exactly like run, but creates a release
tarball for your project additionally. The release files (as specified
in your .cqfdrc) will be included inside the release archive.
$ cqfd release
The resulting release file is then called unique job name, or the string "local-build" when run from outside Jenkins, and BUILD_ID is a Jenkins-generated unique and date-based string, or the current date.
Flavor
You may also want to build a specific build flavor, for a regular build or a release. To do so use the -b option:
$ cqfd -b <flavor_name> run|release
When building with a flavor, as when building a regular project, the
run option can be omitted.
Other command-line options
In some conditions you may want to use an alternate config file with cqfd. This is what the -f option is for:
$ cqfd -f .cqfdrc.test
The codebase contains tests which can be invoked using the following command, if the above requirements are met on the system:
$ make tests
CQFD stands for "Ce qu'il fallait Dockeriser".