2.2. Belle II Software Tools#

The Belle II Software Tools is a collection of script to prepare your environment for the execution of the Belle II software.

2.2.1. Installation#

In case you don’t have a centrally provided Belle II Software you need to install the tools locally. Once you have configured your access to the code repository following the instructions to create your ssh key and upload your public key to GitLab you can obtain the software tools from the central Belle II code repository with the following command:

$ git clone git@gitlab.desy.de:belle2/software/tools.git

Note

We strongly recommend to setup connection over ssh but if you cannot do so you can also obtain the tools using

$ git clone https://gitlab.desy.de/belle2/software/tools.git

where you need to replace username with your DESY username.

After first time installation of the tools you need to run

$ tools/b2install-prepare

to make sure that all software requirements for installing the Belle II Software are met on your Machine.

Note

This will require root permissions

2.2.2. Setup#

Once the tools are installed you need to setup the Belle II environment by sourcing tools/setup_belle2:

$ source tools/b2setup

Warning

This has to be done in every shell you plan on using the Belle II Software.

The behavior of the tools can be customized by setting the following environment variables before sourcing tools/setup_belle2:

BELLE2_USER#

This variable allows you to set the username for any communication to the servers. By default it will be set to the local username.

This variable is helpful if your local username is different to your DESY username.

BELLE2_GIT_ACCESS#

This variable can be set to either http or ssh to specify the protocol to be used for git commands.

ssh

This will use ssh connection to the DESY git server. This is the default and the preferred method but requires that you upload your ssh key to https://gitlab.desy.de .

http

Use https to access the DESY git servers. This works in all cases but will require frequent entering of your desy password.

BELLE2_NO_TOOLS_CHECK#

If set to a non-empty value sourcing the tools will not try to check if the tools version is up to date. This option is useful for laptops without permanent internet connection.

Warning

If you set this on your machine please check regularly that the tools are up to date by running git pull in the tools directory.

VO_BELLE2_SW_DIR#

This should point to the parent directory of the tools directory and indicates where the tools and installed releases are to be found.

BELLE2_EXTERNALS_TOPDIR#

Where to look for the external software. This only needs to be set if you installed the software externals in a different directory. The default is $VO_BELLE2_SW_DIR/externals

BELLE2_EXAMPLES_DATA_DIR#

Where to look for the official examples data. This is assumed to be $VO_BELLE2_SW_DIR/examples but can be set to any location where the data is installed using b2install-data

BELLE2_VALIDATION_DATA_DIR#

Where to look for the official examples data. This is assumed to be $VO_BELLE2_SW_DIR/examples but can be set to any location where the data is installed using b2install-data

BELLE2_BACKGROUND_DIR#

Where to look for background files.

In addition the tools will set or honor the following environment variables

BELLE2_TOOLS#

Directory where the tools are located.

BELLE2_LOCAL_DIR#

If a local release is setup this variable will be set to the directory containing this local release

BELLE2_RELEASE_DIR#

If a central release is setup this variable will be set to the directory containing the central release

BELLE2_EXTERNALS_DIR#

Directory containing the external software package necessary for the currently setup software version (or standalone if using b2setup-externals

2.2.3. Provided Scripts#

The Belle II Software Tools provide a number of scripts common to all software versions to setup and use the Belle II Software.

For users#

b2analysis-create
Usage: b2analysis-create directory release

This command creates a local directory with the given name for the development of analysis code. It also prepares the build system and adds the analysis directory to git.

The second argument specifies the central release on which the analysis should be based.

b2analysis-get
Usage: b2analysis-get directory [username]

This command checks out the analysis code from the given repository name in git. It also prepares the build system.

The optional second argument can be used to specify a user name e.g. to check out the analysis code created by somebody else.

b2analysis-update
Usage: b2analysis-update [release]

This command changes the central release version for the currently set up analysis. If no central release version is given as argument the recommended release version is taken.

b2setup
Usage: b2setup release

This command sets up the environment for the given central release of the Belle II software.

Hint

The b2setup command is also used to set up local releases for developers.

b2setup-externals
Usage: b2setup-externals [externals_version]

This command sets up the Belle II externals to be used without any specific release of the Belle II software. It’s useful if you just want to enable the software included in the Belle II externals like an updated ROOT or git version. Without an argument it will setup the latest version it can find, otherwise it will setup the specified version

b2help-releases
Usage: b2help-releases [release_to_check]

This command just prints the current recommended release of the Belle II software. If you provide release_to_check, it will check if you should be using a more recent version.

b2install-release
Usage: b2install-release [version [system]]

This command installs the given release or build version of basf2 in the directory $VO_BELLE2_TOPDIR/releases. If the operating system is specified it tries to install the corresponding precompiled binary version, otherwise it will try to automatically determine the correct operating system. If no precompiled binary version is available for the given or determined operating system it attempts to compile from source.

If no version is given it lists the available versions.

b2install-externals
Usage: b2install-externals [version [system]]

This command installs the given version of the externals in the directory given by the environment variable BELLE2_EXTERNALS_TOPDIR. If the operating system is specified it tries to install the corresponding precompiled binary version otherwise it will try to automatically determine the correct operating system. If no precompiled binary version is available for the given or determined operating system it attempts to compile the externals from source.

If no version is given it lists the available externals versions.

b2install-data
Usage:: b2install-data datatype

This command installs or updates the given type of basf2 data. Supported data types are ‘validation’ and ‘examples’.

For developers#

b2code-create
Usage: b2code-create directory [release]

This command creates a local directory with the given name as basis for a working copy of the Belle II software. It also prepares the build system.

If the basis for the code development should be a particular release, the version can be given as second argument. If no second argument is given, the latest version of the code (head of git main) is taken.

b2setup
Usage: b2setup [release]

Execute the b2setup command in a local release directory to set it up. If a centrally installed release with the same version as the local one exists, it is set up, too. If a release version is given as argument this is used as version for the central release instead of the one matching the local release.

b2code-style-check

The b2code-style-check tool checks the layout of C++ and python code and reports changes that the b2code-style-fix tool would apply.

By default it checks all C++ and python files in the current directory and its subfolders recursively. Individual files can be checked explicitly by giving them as argument.

Note

No commits can be pushed to the server if b2code-style-check or b2code-style-fix report any problems.

b2code-style-fix
Usage: b2code-style-fix [-n|-p [-d command]] [files]

The b2code-style-fix tool formats the layout of C++ and python code. It helps developers to achieve a common style of all Belle II software.

By default it checks all C++ and python files in the current directory and its subfolders recursively. Individual files can be checked explicitly by giving them as argument.

-n

If this option is given b2code-style-fix only prints the changes which would be applied but the files are not modified. The return code indicates the number of files that would be changed.

-p

This option is equivalent to -n except that it will print the pep8 and flake8 output instead of the code changes.

-d command

This option can be used to specify the diff command that is called to report changes. Has to be given after the -n or -p option.

Note

No commits can be pushed to the server if b2code-style-check or b2code-style-fix report any problems.

b2code-clean

This command deletes all built includes, object files, libraries, modules, and executables of your current local release. The prompt for confirmation can be disabled with the -f option.

-f

Don’t ask for confirmation

b2code-package-list
Usage: b2code-package-list [-l] [-s]

This command lists the available packages. It has to be called in the local release directory.

-l

Also print the responsible librarians.

-s

Exclude locally installed packages

b2code-package-add
Usage: b2code-package-add package

This command adds the source code of the given package from the code repository to the local release directory. It has to be called in the local release directory with the name of one package.

b2code-package-tag
Usage: b2code-package-tag ["major"/"minor"/"patch"(=default)/tag]

  • This command tags the current version of the source code of a package and pushes the tag to the central repository. It has to be called in the package directory of the local release. There should be no locally modified files.

  • If no argument is given, the tag name is chosen automatically by increasing the patch level number, e.g. from v01-01-01 to v01-01-02.

  • If “minor” is given as argument, the minor version number is increased, e.g. from v01-01-01 to v01-02-01.

  • If “major” is given as argument, the major version number is increased, e.g. from v01-01-01 to v02-01-01.

  • Alternatively the name of the tag can be given explicitly as argument.

b2install-prepare
Usage: b2install-prepare [--non-interactive] [--optionals]

If executed without arguments it will check if all necessary packages are installed and if not it will ask the user if it should do it.

If –non-interactive is given it will not ask but just install the necessary packages but not the optional ones. If –optionals is given as well it will install everything without asking.