bob-dev - Bob develop mode build
bob dev [-h] [--destination DEST] [-j [JOBS]] [-k] [-f] [-n] [-p] [--without-provided] [-A | --audit] [-b | -B | --normal] [--clean | --incremental] [--always-checkout RE] [--resume] [-q] [-v] [--no-logfiles] [-D DEFINES] [-c CONFIGFILE] [-e NAME] [-E] [-M META] [--upload] [--link-deps] [--no-link-deps] [--download MODE] [--download-layer MODE] [--shared | --no-shared] [--install | --no-install] [--sandbox | --no-sandbox] [--clean-checkout] PACKAGE [PACKAGE ...]
The bob dev command is building packages locally in develop mode. This mode is intended to be used by developers to incrementally build the packages. Its defaults are tuned to support active development on source code by keeping a stable directory structure and minimize the edit-compile turnaround time.
By default bob dev works in the
dev subdirectory of the project root
directory. The source-, build- and package-directories are kept in separate
dev/dist) to allow easy
indexing of the involved sources by IDEs. It is possible to change these paths
by means of a plugin but it is advised to keep the top level structure.
In contrast to bob build the following options take precedence. They can be overridden individually by their inverse switches:
Source code checkout¶
The source workspaces are updated incrementally as good as possible even across recipe changes. This works quite well e.g. for git repositories. It could fail silently on certain some recipes, though. On URL-SCMs the downloaded file can be tracked by Bob. But if an archive is extracted Bob cannot reliably know which files were coming from the archive. If the archive changes and files vanish they will still be kept in the workspace.
If a binary archive is used Bob will try to skip the checkout of sources if possible. This will work only if matching binary artifacts are available for the current state of the recipes and their configuration. Though this will typically speed up the build it can actually make working on the source code difficult because not all involved sources are checked out.
There are a number of options to force the checkout of sources is such an environment:
- Use the
--always-checkoutoption. If you’re typically working on some particular packages then this option can force the checkout of these sources. It can be set in default.yaml so that it does not need to be specified every time again.
- Make a dedicated build of selected packages. Because of
--download=depsthe specified package will always be built from source.
--checkout-onlyto fetch the sources of a package and all its dependencies.
In any case Bob will use the sources once they were checked out. Bob will also update them in subsequent builds.
Build tree location¶
The build can be done directly in the project root directory or in a separate
directory. To build outside of the project directory the build-tree must first
be initialized with bob init. Any number of build
trees may refer to the same project. Inside the external build-tree there may
be a dedicated
default.yaml, overriding settings from the project.
Always checkout packages that match the regular expression pattern
RE. The option may be given more than once. In this case all patterns will be checked.
Bob may skip the checkout of packages where a correct binary artifact can be downloaded from an archive. While this can dramatically decrease the build time of large projects it can hamper actually changing and rebuilding the packages with modifications. Use this option to instruct Bob to always checkout the sources of the packages that you may want to modify.
This option will just make sure that the sources of matching packages are checked out. Bob will still try to find matching binary artifacts to skip the actual compilation of these packages. See the
--download-layeroption to control what is built and what is downloaded.
Generate an audit trail when building.
This is the default unless the user changed it in
Do clean builds by clearing the build directory before executing the build commands. It will not clean all build results (e.g. like
make clean) but rather make sure that no old build artifacts are in the workspace when a package is rebuilt. To actually force a rebuild (even though nothing has changed) use
This is the default for release mode builds. See
--incrementalfor the inverse option.
Do a clean checkout if SCM state is unclean.
Bob will check all SCMs for local changes at the start of a checkout. If a SCM checkout is tainted (e.g. dirty, switched branch, unpushed commits, …) Bob will move it into the attic and do a fresh checkout.
Use this option if you are not sure about the state of the source code. You can also use ‘bob status’ to check the state without changing it.
Destination of build result (will be overwritten!)
All build results are copied recursively into the given folder. Colliding files will be overwritten but other existing files or directories are kept. Unless
--without-providedis given using this option will implicitly enable
--with-providedto build and copy all provided packages of the built package(s).
Download from binary archive (yes, no, deps, forced, forced-deps, packages)
- build given module and it’s dependencies from sources
- download given module, if download fails - build it from sources (default for release mode)
- like ‘yes’ above, but fail if any download fails
- download dependencies of given module and build the module afterwards. If downloading of any dependency fails - build it from sources (default for develop mode)
- like ‘deps’ above, but fail if any download fails
- combination of forced and forced-deps modes: if forced fails fall back to forced-deps
- packages=<packages regex>
- download modules that match a given regular expression, build all other.
Download from binary archive for layer (yes, no, forced)
--downloadbut only for the modules of the layer that match a given regular expression (
--downloadoption will be overwritten for matching modules). Can be used multiple times (if regex is used also multiple times the last mode wins). A sub layer is separated with a
- no=<layer regex>
- build modules of a layer that match a given regular expression from sources
- yes=<layer regex>
- download modules of a layer that match a given regular expression, if download fails - build it from sources
- forced=<layer regex>
- like ‘yes’ above, but fail if any download fails
Reuse build directory for incremental builds.
This is the inverse option to
--clean. Build workspaces will be reused as long as their recipes were not changed. If the recipe did change Bob will still do a clean build automatically.
- Install shared packages. A shared location must have been configured so that Bob knows where to put the package. This is the default.
- Create symlinks to dependencies next to workspace.
- Do not install shared packages if a shared location is configured.
- Disable sandboxing
- Do not use shared packages even if they are available.
Resume build where it was previously interrupted.
All packages that were built in the previous invocation of Bob are not checked again. In particular changes to the source code of these packages are not considered. Use this option to quickly resume the build if it failed and the error has been corrected in the failing package.
- Enable sandboxing
- Use shared packages if they are available. This is the default.
- Upload to binary archive
Do not generate an audit trail.
The generation of the audit trail is usually barely noticeable. But if a large number of repositories is checked out it can add a significant overhead nonetheless. This option suppresses the generation of the audit trail.
Note that it is not possible to upload such built artifacts to a binary archive because vital information is missing. It is also not possible to install shared packages that were built without audit trail for the same reason.
- Don’t build, just check out sources
Override default or set environment variable.
Sets the variable
VALUE. This overrides the value possibly set by
default.yaml, config files passed by
-cor any file that was included by either of these files.
Preserve whole environment.
Normally only variables configured in the whitelist are passed unchanged from the environment. With this option all environment variables that are set while invoking Bob are kept. Use with care as this might affect some packages whose recipes are not robust.
- Assign the meta variable
VARto the given value in the audit trail. The variable can later be matched by bob archive as
meta.VARto select artifacts built by this project. Variables that are defined by Bob itself (e.g.
meta.bob) cannot be redifined!
Don’t checkout, just build and package
If the sources of a package that needs to be built are missing then Bob will still check them out. This option just prevents updates of existing source workspaces that are fetched from remote locations. A notable exception is the
importSCM which will still update the workspace even if this option is present.
Use additional configuration file.
.yamlsuffix is appended automatically and the configuration file is searched relative to the project root directory unless an absolute path is given. Bob will parse these user configuration files after default.yaml. They are using the same schema.
This option can be given multiple times. The files will be parsed in the order as they appeared on the command line.
Preserve environment variable.
-Ethis allows the fine grained addition of single environment variables to the whitelist.
Force execution of all build steps.
Usually Bob decides if a build step or any of its input has changed and will skip the execution of it if this is not the case. With this option Bob not use that optimization and will execute all build steps.
Specifies the number of jobs to run simultaneously.
Any checkout/build/package step that needs to be executed are counted as a job. Downloads and uploads of binary artifacts are separate jobs too. If a job fails the other currently running jobs are still finished before Bob returns. No new jobs are scheduled, though, unless the
-koption is given (see below).
If the -j option is given without an argument, Bob will run as many jobs as there are processors on the machine.
Continue as much as possible after an error.
While the package that failed to build and all the packages that depend on it cannot be built either, the other dependencies are still processed. Normally Bob stops on the first error that is encountered.
Don’t build dependencies.
Only builds the package that was given on the command line. Bob will not check if the dependencies of that package are available and if they are up-to-date.
- Do not create symlinks to dependencies next to workspace.
- Don’t write a logfile. Without this bob is creating a logfile in the current workspace. Because of the pipe-usage many tools like gcc, ls, git detect they are not running on a tty and disable output coloring. Disable the logfile generation to get the colored output back.
- Build provided dependencies too. In combination with
--destinationthis is the default. In any other case
- Decrease verbosity (may be specified multiple times)
- Increase verbosity (may be specified multiple times)
- Build just the named packages without their provided dependencies. This is
the default unless the
--destinationoption is given too.