Develop Code

Last update: 06 Aug 2024 [History] [Edit]

Development

Making changes to the code you can now do in your favourite editor or IDE (see IDE Integrations for recommendations). But do remember that you have the power of a local git repository at your fingertips:

  • You can commit code locally anytime, to make it easy to rollback to a known development snapshot
  • You can even do more speculative development on a branch from your main topic branch - merge it in if it works, throw it away if it doesn’t

It’s recommended to commit early, commit often for every coherent piece of the larger change you are working on.

Setting up to compile and test code for the tutorial

You now need to setup a base athena release on which to add your code changes. So setup a suitable release like this in a new build area:

mkdir ../build && cd ../build  # Assuming you start in the root
                               # of your git clone, but in fact
                               # you can do this anywhere outside
                               # the source area
asetup main,latest,Athena

The asetup command will setup a runtime environment for the main branch build of Athena that was built most recently. There is more information on working with nightly builds here including how to check which releases are actually available at the time you do the tutorial.

Here we are picking the runtime for the branch we want to work with, which is of course the same as our target branch.

If you ran the normal cmake; make cycle you would rebuild the entire offline release - this would take a long time and it’s almost certainly not what you want. Instead you want to only rebuild part of the release, which is a sparse build.

To do that take a local copy of Projects/WorkDir/package_filters.txt and edit it to list only the packages you want to build. Then run CMake using the options shown below:

cp ../athena/Projects/WorkDir/package_filters_example.txt ../package_filters.txt
EDITOR ../package_filters.txt
# Plain setup 
cmake -DATLAS_PACKAGE_FILTER_FILE=../package_filters.txt ../athena/Projects/WorkDir
# Or if you are using VSCode as your IDE:
cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=TRUE -DATLAS_ENABLE_IDE_HELPERS=TRUE -DATLAS_PACKAGE_FILTER_FILE=../package_filters.txt ../athena/Projects/WorkDir
make -j

Tip For more information about using VSCode when developing Athena (and for an explanation of DCMAKE_EXPORT_COMPILE_COMMANDS and DATLAS_ENABLE_IDE_HELPERS above), see the VSCode guide (especially the Setup section).

Tip The syntax of package_filters.txt is very simple:

  • +PATH_REGEXP adds these PATH entries to the build
  • -PATH_REGEXP removes these PATH entries from the build
    The first match wins.

Tip As in the above example keeping your package_filters.txt in a different directory from the build is wise, so you can rm -fr * your build area. Just don’t keep it in the git repository as there is a danger you would commit it by mistake.

Bad Using a sparse build is extremely flexible, but it’s an extra step. The alternative sparse checkout is be easier in most cases, at the loss of some flexibility (having the entire codebase visible in your IDE can be very convenient).

Bad If any package in a sparse checkout or your package_filters.txt builds OBJECT libraries, you must add the package that incorporates it into a final SHARED or STATIC “big/fat” library to file/checkout. This is required to force re-linking of the main library so that your changes are reflected in your local build and test. At present, this only affects packages that use Geant4 or CUDA. Work is in progress to make the addition of the “big/fat” package to package_filters.txt automatic.

Local testing and code quality

As with all ATLAS CMake builds you will need to source your build area setup to run properly. e.g.,

mkdir ../run && cd ../run
source ../build/x86_64-slc6-gcc49-opt/setup.sh
Reco_tf.py --AMI q431  # Or your own favourite test!

Though note that your architecture (x86_64-slc6-gcc49-opt) may be different.

Good developers test their code during development and we are sure that you are no different. For new features try and develop unit tests if you can.