ldmx/dev repository overview

⁠Development Environment for ldmx-sw and ldmx-analysis

This container, along with a few helpful aliases, will allow you to build and run ldmx-sw and its related softwares in a isolated container separate from the rest of your computer without installing any other dependencies. This container depends on mounting your files to the container so that both the docker container and your system are looking at the same files. This allows you to continue using whatever operating system, text editor, root version, etc without getting in the way of the building and running of ldmx-sw.

⁠Setup

In order to mount your contents on the docker container, it is helpful to define an environment variable that will be used by you and the docker container: LDMX_BASE. This environment variable must be spelled and capitalized this way because it will be passed into the docker container by name.

In bash:

export LDMX_BASE=<path-to-directory-containing-ldmx-sw>

Now in order to run a command in the ldmx environment (inside the container), you will need a long docker command. It is helpful to define an alias for this command because it will not change during your configure/build/run workflow. Again in bash:

alias ldmx='docker run --rm -it -e LDMX_BASE -v $LDMX_BASE:$LDMX_BASE -u $(id -u ${USER}):$(id -g ${USER}) ldmx/dev:latest $(pwd)'

Let me explain each part of this command:

• docker : base docker command, you will need to give yourself special access to run docker without root access⁠. Alternatively, you can put sudo (or your system's equivalent) in front of docker, and then you will have to enter your password everytime you run.
• run : instead of building or pulling or pushing an image, we are going to run the image as a container
• --rm : delete the container after the command is done, this cleans up after us, maybe don't need this???
• -it : allows the host (your computer) to pass signals to the docker container (e.g. ctrl-C)
• -e LDMX_BASE : pass the environment variable LDMX_BASE from your current environment to the container environment
• -v $LDMX_BASE:$LDMX_BASE : mount the directory $LDMX_BASE onto the same location in the container
• -u $(id -u ${USER}):$(id -g ${USER}) : runs the docker command with the permissions of the current user and that user's group
• ldmx/dev:latest : the image we want to use to make the container to run in
• $(pwd) : the image's entrypoint takes two arguments. The first is the directory to go to inside the container and then the rest is the command to be executed. This last part moves us to the same location after entering the container so our command runs in the same place we intended. The rest of the arguments passed to the image is whatever comes after this alias.

⁠Use

With the setup we did earlier, we can start doing nonsense like building, installing, and running ldmx-sw. A simple way to think about the ldmx command is that it puts your next command into the docker container to run. Since you mounted your working files onto the container in the same place, it has access to and can read/write the files there. Thus, the following commands outline building, installing, and running:

$ cd ldmx-sw; mkdir build; cd build
$ ldmx cmake ..
$ ldmx make -j2 install
$ ldmx ldmx-app config.py

⁠Assumptions

The base assumption of this container is that you have defined the environment variable LDMX_BASE correctly and the rest of your files inside of LDMX_BASE have a specific format.

$LDMX_BASE
├── ldmx-analysis
│   ├── install
|    |   ├── lib (created automatically by installation)
|    |   |     ├── python (created automatically by installation)
|    |   ├── bin (created automatically by installation)
│   │   ...other code/scripts
├── ldmx-sw
│   ├── install
|    |   ├── lib (created automatically by installation)
|    |   |     ├── python (created automatically by installation)
│   │   ...other code/scripts
| ...other code/scripts

This ensures that when you build/install/run, the container knows where certain files that it needs are. The entrypoint script is intended to define the ldmx running environment so that your command can run inside of it; thus, the container needs to already know where the various installations are so that it can point the container's PATH, PYTHONPATH, and LD_LIBRARY_PATH to the correct directories.

⁠Warnings

docker acts as a root user on most systems, so any files it writes will be owned by root. This may be a problem on some shared systems, so please consult with your institutions IT if you want to use this system on shared computing resources. Additionally, on your personal computer, you will only be able to delete docker-made files if you use sudo or delete them using docker. For example, suppose I want to delete the build I made earlier:

$ cd ldmx-sw/build
$ rm -rf *
...Permission denied error...
$ ldmx rm -rf * #works