Repository files navigation

Simulation and reconstruction framework for the Light Dark Matter eXperiment.

ldmx-sw is a large software project and so it is helpful to separateusing it toperform physics studies fromdeveloping it to fix/improve/enable other studies.In both cases, we use containers to share a fixed software environment, so everyonewill need a method for running these containers.

• Install the docker engine
  • Only necessary on personal computers. Shared computing clusters should haveapptainer installed.
  • (on Linux personal computers)Manage docker as non-root user
• Installdenv

curl -s https://raw.githubusercontent.com/tomeichlersmith/denv/main/install | sh

Some folks may see an error about something not being within yourPATH,you just need to update your shell's configuration to look fordenv withinthat directory.A program being "in yourPATH" can be checked by making sure your shellcan find it.

denv help

The above should printout a help message instead of a "command not found"message.

Additionally, many folks have gotten used to usingldmx as the commandto put programs into the containerized environment in which case you canuse the following to add this symlink to yourdenv installation.(Note: This requiresdenv to be in yourPATH!).

ln -s $(which denv) $(dirname $(which denv))/ldmx

In order to use ldmx-sw, no more dependencies are required!Simply choose the version of ldmx-sw you wish to use with your project.

mkdir my-projectcd my-projectdenv init ldmx/pro:v4.0.1 # or some other ldmx-sw version

And then you can run ldmx-sw with a configuration script of your choice.

denv fire my-config.py

More detail on configuration scripts and analyzing the output filesis given in the first section of theonline manual.

For development, we use a few more tools to help track our changes and share commandsthat we use regularly.

• Make suregit is installed.
  • git is a very common tool used by software developers and so it may already be available.
  • (on MacOS systems) Make suregit lfs is installed. (Test:git lfs prints out a help message instead of an error aboutlfs not being found.) The default installation ofgit that is included with Apple's developer tools does not includegit lfs which is required by acts to download and unpack one of its own submodules.GitHub has a nice tutorial on how to installgit lfs on MacOS.
• Installjust
  • This tool is not required but it is highly encouraged. The recipes we share via thejustfile can be run withoutjust but are longer to type.

One can installjust in a similar way todenv. Below is an example where thedestination directory is set to the same one as the default fordenv (~/.local/bin).

curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh |\  bash -s -- --to ~/.local/bin

Otherpackage manager options are availableas well.You will probably want to make surejust's tab complete is available.If you pressjust -<Tab><Tab> and nothing is listed, then the tab complete isnot present and you must manually install it.This can be accomplished by including its completions within your shell'sconfiguration script. For example, inbash, we would add the followingto your~/.bashrc file.

eval "$(just --completions bash)"

If you are not inbash, look to your shell's documentation on where to placethis line.just supports many popular shells includingbash,zsh, andfish.

With these additional tools, developers can clone the repository and start development.

git clone --recursive git@github.com:LDMX-Software/ldmx-sw.git

cd ldmx-swjust # no arguments prints out the possible optionsjust init # initialize a new development environment (once per clone)just configure build test # configure ldmx-sw, build it, then test it