From 90acde888ff00fc30a4462034f3192ae5068a708 Mon Sep 17 00:00:00 2001 From: tomeichlersmith Date: Tue, 5 Aug 2025 11:37:18 -0500 Subject: [PATCH 1/9] remove entrypoint script now that denv has been more fully adopted --- Dockerfile | 7 ------- entry.sh | 16 ---------------- 2 files changed, 23 deletions(-) delete mode 100755 entry.sh diff --git a/Dockerfile b/Dockerfile index ea1b769..4656cc8 100644 --- a/Dockerfile +++ b/Dockerfile @@ -452,10 +452,3 @@ RUN printf "%s\n" \ "fi" \ ". /etc/ldmx-env-init.sh" \ >> /etc/skel/.profile - -#run environment setup when docker container is launched and decide what to do from there -# will require the environment variable LDMX_BASE defined -COPY ./entry.sh /etc/ -RUN chmod 755 /etc/entry.sh -ENTRYPOINT ["/etc/entry.sh"] - diff --git a/entry.sh b/entry.sh deleted file mode 100755 index 93975e5..0000000 --- a/entry.sh +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/bash - -set -e - -source /etc/ldmx-env-init.sh - -# puts a config/cache directory for matplotlib to use -# does /not/ need to be in the ldmx-env-init.sh script since denv-based -# interactions with the image define LDMX_BASE as HOME for us anyways -export MPLCONFIGDIR=$LDMX_BASE/.config/matplotlib - -# go to first argument -cd "$1" - -# execute the rest as a one-liner command -eval "${@:2}" From 925f6c03c1a81d15f9e5f87f2b5a5f24b878013e Mon Sep 17 00:00:00 2001 From: tomeichlersmith Date: Tue, 5 Aug 2025 11:37:40 -0500 Subject: [PATCH 2/9] put GENIE ld libs and PATH into image build at temp location --- Dockerfile | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Dockerfile b/Dockerfile index 4656cc8..05cdf78 100644 --- a/Dockerfile +++ b/Dockerfile @@ -442,6 +442,12 @@ RUN install-ubuntu-packages \ COPY ./certs/ /usr/local/share/ca-certificates RUN update-ca-certificates +# temporary change to make test build faster, remove before merge +RUN echo "${GENIE}/lib" > /etc/ld.so.conf.d/genie.conf &&\ + echo "${GENIE_REWEIGHT}/lib" > /etc/ld.so.conf.d/genie-reweight.conf &&\ + ldconfig -v +ENV PATH="${PATH}:${GENIE}/bin:${GENIE_REWEIGHT}/bin" + # copy environment initialization script into container # and make sure the default profile will call it as well COPY ./ldmx-env-init.sh /etc/ From 87fa964460d4e596aa6e61956109691cc2798609 Mon Sep 17 00:00:00 2001 From: tomeichlersmith Date: Tue, 5 Aug 2025 11:38:32 -0500 Subject: [PATCH 3/9] don't define LDMX_BASE, update LDMX_SW_INSTALL deduction - support ldmx-sw being HOME or inside HOME - remove GENIE LD_LIBRARY_PATH and PATH now in image - cleanup CMAKE_PREFIX_PATH deduction --- Dockerfile | 4 ---- ldmx-env-init.sh | 40 +++++++++++++++++++++++++--------------- 2 files changed, 25 insertions(+), 19 deletions(-) diff --git a/Dockerfile b/Dockerfile index 05cdf78..32a6589 100644 --- a/Dockerfile +++ b/Dockerfile @@ -452,9 +452,5 @@ ENV PATH="${PATH}:${GENIE}/bin:${GENIE_REWEIGHT}/bin" # and make sure the default profile will call it as well COPY ./ldmx-env-init.sh /etc/ RUN printf "%s\n" \ - "# make sure LDMX_BASE is defined for ldmx-env-init.sh" \ - "if [ -z \"\${LDMX_BASE+x}\" ]; then" \ - " export LDMX_BASE=\"\${HOME}\"" \ - "fi" \ ". /etc/ldmx-env-init.sh" \ >> /etc/skel/.profile diff --git a/ldmx-env-init.sh b/ldmx-env-init.sh index 8c6f2ca..9df3450 100644 --- a/ldmx-env-init.sh +++ b/ldmx-env-init.sh @@ -5,24 +5,37 @@ # or it is located at LDMX_BASE/ldmx-sw/install. ############################################################################### -# add ldmx-sw and ldmx-analysis installs to the various paths # LDMX_SW_INSTALL is defined when building the production image or users # can use it to specify a non-normal install location if [ -z "${LDMX_SW_INSTALL+x}" ]; then if [ -z "${LDMX_BASE+x}" ]; then - printf "[ldmx-env-init.sh] WARNING: %s\n" \ - "Neither LDMX_BASE nor LDMX_SW_INSTALL is defined." \ - "At least one needs to be defined to ensure a working installation." + # LDMX_BASE not defined + if [ -f "${HOME}/CMakeLists.txt" ]; then + # HOME is ldmx-sw + export LDMX_SW_INSTALL="${HOME}/install" + elif [ -d "${HOME}/ldmx-sw" ]; then + # HOME is ldmx-sw's parent directory + export LDMX_SW_INSTALL="${HOME}/ldmx-sw/install" + else + # unable to auto-detect + printf "[ldmx-env-init.sh] WARNING: %s\n" \ + "LDMX_SW_INSTALL is not defined and I wasn't able to deduce the location relative to ${HOME}." \ + "You may not be able to run ldmx-sw programs in this environment." + fi + else + # LDMX_BASE defined + export LDMX_SW_INSTALL="${LDMX_BASE}/ldmx-sw/install" fi - export LDMX_SW_INSTALL="${LDMX_BASE}/ldmx-sw/install" fi -export LD_LIBRARY_PATH="${LDMX_SW_INSTALL}/lib:${LD_LIBRARY_PATH}" -export PYTHONPATH="${LDMX_SW_INSTALL}/python:${LDMX_SW_INSTALL}/lib:${PYTHONPATH}" -export PATH="${LDMX_SW_INSTALL}/bin:${PATH}" -#add what we need for GENIE -export LD_LIBRARY_PATH="${GENIE}/lib:${GENIE_REWEIGHT}/lib:/usr/local/pythia6:${LD_LIBRARY_PATH}" -export PATH="${GENIE}/bin:${GENIE_REWEIGHT}/bin:${PATH}" +export CMAKE_PREFIX_PATH="/usr/local/" + +if [ -n "${LDMX_SW_INSTALL+x}" ]; then + export LD_LIBRARY_PATH="${LDMX_SW_INSTALL}/lib:${LD_LIBRARY_PATH}" + export PYTHONPATH="${LDMX_SW_INSTALL}/python:${LDMX_SW_INSTALL}/lib:${PYTHONPATH}" + export PATH="${LDMX_SW_INSTALL}/bin:${PATH}" + export CMAKE_PREFIX_PATH="${CMAKE_PREFIX_PATH}:${LDMX_SW_INSTALL}" +fi # Developer option: If a custom geant4 install is to be used, source the # environment script from that install @@ -61,7 +74,7 @@ if [ -n "${LDMX_CUSTOM_GEANT4+x}" ]; then # shellcheck disable=SC1091 . "${LDMX_CUSTOM_GEANT4}/bin/geant4.sh" # Prioritize the cmake config in the Geant4 installation over the container location (/usr/local) - export CMAKE_PREFIX_PATH="${LDMX_CUSTOM_GEANT4}/lib/cmake:/usr/local/:${CMAKE_PREFIX_PATH}" + export CMAKE_PREFIX_PATH="${LDMX_CUSTOM_GEANT4}/lib/cmake:${CMAKE_PREFIX_PATH}" # If no directory was found by the geant4.sh script and the user didn't # explicitly ask for a location (e.g. for a debug build): @@ -70,7 +83,4 @@ if [ -n "${LDMX_CUSTOM_GEANT4+x}" ]; then if [ -z "${GEANT4_DATA_DIR+x}" ]; then export GEANT4_DATA_DIR="${G4DATADIR}" fi -else - # Tell CMake to look for configuration files in the container location by default - export CMAKE_PREFIX_PATH="/usr/local/:${LDMX_SW_INSTALL}" fi From 8faac912079871a8f387b294abfbfc6ad0cd7ab6 Mon Sep 17 00:00:00 2001 From: tomeichlersmith Date: Tue, 5 Aug 2025 15:38:33 -0500 Subject: [PATCH 4/9] update comments in init script --- ldmx-env-init.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ldmx-env-init.sh b/ldmx-env-init.sh index 9df3450..7a32f55 100644 --- a/ldmx-env-init.sh +++ b/ldmx-env-init.sh @@ -2,7 +2,7 @@ # Environment initialization for LDMX SW container images # Assumptions: # - The installation location of ldmx-sw is defined in LDMX_SW_INSTALL -# or it is located at LDMX_BASE/ldmx-sw/install. +# or it is located at ${HOME}/ldmx-sw/install or ${HOME}/install. ############################################################################### # LDMX_SW_INSTALL is defined when building the production image or users From e28e2f65fc377afc5b281fd6e8cff4ddf93ad0a2 Mon Sep 17 00:00:00 2001 From: tomeichlersmith Date: Tue, 5 Aug 2025 11:40:28 -0500 Subject: [PATCH 5/9] move genie ld libs and PATH defs to where GENIE is built --- Dockerfile | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/Dockerfile b/Dockerfile index 32a6589..2e554cc 100644 --- a/Dockerfile +++ b/Dockerfile @@ -316,7 +316,9 @@ RUN mkdir -p ${GENIE} &&\ --with-hepmc3-inc=/usr/local/include \ && \ make -j$NPROC && \ - make -j$NPROC install + make -j$NPROC install && \ + echo "${GENIE}/lib" > /etc/ld.so.conf.d/genie.conf +ENV PATH="${PATH}:${GENIE}/bin" ENV GENIE_REWEIGHT_VERSION=1_04_00 ENV GENIE_REWEIGHT=/usr/local/src/GENIE/Reweight @@ -326,7 +328,10 @@ RUN mkdir -p ${GENIE_REWEIGHT} &&\ ${__untar_to} ${GENIE_REWEIGHT} &&\ cd ${GENIE_REWEIGHT} &&\ make -j$NPROC && \ - make -j$NPROC install + make -j$NPROC install && \ + echo "${GENIE_REWEIGHT}/lib" > /etc/ld.so.conf.d/genie-reweight.conf +ENV PATH="${PATH}:${GENIE_REWEIGHT}/bin" + ############################################################################### # Catch2 @@ -442,12 +447,6 @@ RUN install-ubuntu-packages \ COPY ./certs/ /usr/local/share/ca-certificates RUN update-ca-certificates -# temporary change to make test build faster, remove before merge -RUN echo "${GENIE}/lib" > /etc/ld.so.conf.d/genie.conf &&\ - echo "${GENIE_REWEIGHT}/lib" > /etc/ld.so.conf.d/genie-reweight.conf &&\ - ldconfig -v -ENV PATH="${PATH}:${GENIE}/bin:${GENIE_REWEIGHT}/bin" - # copy environment initialization script into container # and make sure the default profile will call it as well COPY ./ldmx-env-init.sh /etc/ From be2223ac466302b8f9725a85686ea8958d8534cc Mon Sep 17 00:00:00 2001 From: tomeichlersmith Date: Thu, 7 Aug 2025 09:23:28 -0500 Subject: [PATCH 6/9] remove custom Geant4 scripting --- ldmx-env-init.sh | 48 ------------------------------------------------ 1 file changed, 48 deletions(-) diff --git a/ldmx-env-init.sh b/ldmx-env-init.sh index 7a32f55..2534061 100644 --- a/ldmx-env-init.sh +++ b/ldmx-env-init.sh @@ -36,51 +36,3 @@ if [ -n "${LDMX_SW_INSTALL+x}" ]; then export PATH="${LDMX_SW_INSTALL}/bin:${PATH}" export CMAKE_PREFIX_PATH="${CMAKE_PREFIX_PATH}:${LDMX_SW_INSTALL}" fi - -# Developer option: If a custom geant4 install is to be used, source the -# environment script from that install -# -# Note: Use with care! -# -# The custom Geant4 install still needs to have been built with the same -# container environment -if [ -n "${LDMX_CUSTOM_GEANT4+x}" ]; then - # Overly obnoxious warning to make sure this feature isn't used accidentally - # Also detail how to set custom Geant4 data directories - if [ -z "${LDMX_CUSTOM_GEANT4_CONFIRM_DEV+x}" ]; then - echo "Warning: You are relying on a non-container version of Geant4. This mode of operation can come with some reproducibility concerns if you aren't careful. " - echo "Define the environment variable LDMX_CUSTOM_GEANT4_CONFIRM_DEV in the container environment to suppress this message" - echo "If using the standard ldmx-env.sh shell script, use 'ldmx setenv' to set environment variables within the container environment" - echo "You may also want to define LDMX_CUSTOM_GEANT4_DATA_DIR if you are using a version of Geant4 different from 10.2.3 and the Geant4 build you intend to use has the data directory in an non-standard location (i.e. one that isn't picked up by the geant4.sh script) " - fi - # First: Unset the container-specific versions of the Geant4 data directories - unset G4NEUTRONHPDATA - unset G4LEDATA - unset G4LEVELGAMMADATA - unset G4RADIOACTIVEDATA - unset G4PARTICLEXSDATA - unset G4PIIDATA - unset G4REALSURFACEDATA - unset G4SAIDXSDATA - unset G4ABLADATA - unset G4INCLDATA - unset G4ENSDFSTATEDATA - unset G4NEUTRONXSDATA - # If explicitly requested, use a custom location for Geant4's data directories - if [ -n "${LDMX_CUSTOM_GEANT4_DATA_DIR+x}" ]; then - export GEANT4_DATA_DIR="${LDMX_CUSTOM_GEANT4_DATA_DIR}" - fi - # Source the custom geant's environment script - # shellcheck disable=SC1091 - . "${LDMX_CUSTOM_GEANT4}/bin/geant4.sh" - # Prioritize the cmake config in the Geant4 installation over the container location (/usr/local) - export CMAKE_PREFIX_PATH="${LDMX_CUSTOM_GEANT4}/lib/cmake:${CMAKE_PREFIX_PATH}" - - # If no directory was found by the geant4.sh script and the user didn't - # explicitly ask for a location (e.g. for a debug build): - # - # Assume we are using 10.2.3 (container provided) data - if [ -z "${GEANT4_DATA_DIR+x}" ]; then - export GEANT4_DATA_DIR="${G4DATADIR}" - fi -fi From ca306814ab67e2ea1335f4451d725e307f2be92b Mon Sep 17 00:00:00 2001 From: tomeichlersmith Date: Thu, 7 Aug 2025 09:45:55 -0500 Subject: [PATCH 7/9] first draft of updating documentation of custom geant4 --- docs/src/custom-geant4.md | 94 +++++++++++++++++++++++++++++++++++---- 1 file changed, 86 insertions(+), 8 deletions(-) diff --git a/docs/src/custom-geant4.md b/docs/src/custom-geant4.md index bc7c6b8..bebf21a 100644 --- a/docs/src/custom-geant4.md +++ b/docs/src/custom-geant4.md @@ -3,10 +3,6 @@ Geant4 is our main simulation engine and it has a large effect on the products of our simulation samples. As such, it is very common to compare multiple different versions, patches, and tweaks to Geant4 with our simulation. -With release 4.2.0 of the ldmx/dev image, the entrypoint script now checks the environment variable `LDMX_CUSTOM_GEANT4` for a path to a local installation of Geant4. -This allows the user to override the Geant4 that is within the image with one that available locally. In this way, you can choose whichever version of Geant4 you want, -with whatever code modifications applied, with whatever build instructions you choose. - ~~~admonish warning title="Confirm Image Version" Make sure you have an image that is at least v4.2.0. You can check your version of the image by [inspecting the image labels](image-version.md). @@ -29,7 +25,7 @@ Now building Geant4 from source has a lot of configuration options that can be u Below are a few that are highlighted for how we use containers and their interaction with the Geant4 build. - `CMAKE_INSTALL_PREFIX`: This should be set to a path accessible from the container so that the programs within the container can read from and write to this directory. If the geant4 build directory is within `LDMX_BASE` (like it is above), then you could do something like `-DCMAKE_INSTALL_PREFIX=../install` when you run `ldmx cmake` within the build directory. -- `GEANT4_INSTALL_DATADIR`: If you are building a version of Geant4 that has the same data files as the Geant4 version built into the container image, then you can tell the Geant4 build to use those data files with this option, saving build time and disk space. This is helpful if (for example) you are just re-building the same version of Geant4 but in Debug mode. You can see where the Geant4 data is within the container with `ldmx 'echo ${G4DATADIR}'` and then use this value `-DGEANT4_INSTALL_DATADIR=/usr/local/share/geant4/data`. +- `GEANT4_INSTALL_DATADIR`: If you are building a version of Geant4 that has the same data files as the Geant4 version built into the container image, then you can tell the Geant4 build to use those data files with this option, saving build time and disk space. This is helpful if (for example) you are just re-building the same version of Geant4 but in Debug mode. You can see where the Geant4 data is within the container with `denv printenv G4DATADIR` and then use this value `-DGEANT4_INSTALL_DATADIR=/usr/local/share/geant4/data`. The following are the build options used when setting up the container and are likely what you want to get started - `-DGEANT4_USE_GDML=ON` Enable reading geometries with the GDML markup language which is used in LDMX-sw for all our geometries @@ -64,8 +60,8 @@ electromagneticParameters->SetGeneralProcessActive(false); - `G4ABLADATA` - `G4INCLDATA` - `G4ENSDFSTATEDATA` -- When using CMake, ensure that the right version of Geant4 is picked up at configuration time (i.e. when you run `ldmx cmake`) - - You can always check the version that is used in a build directory by running `ldmx ccmake .` in the build directory and searching for the Geant4 version variable +- When using CMake, ensure that the right version of Geant4 is picked up at configuration time (i.e. when you run `denv cmake`) + - You can always check the version that is used in a build directory by running `denv ccmake .` in the build directory and searching for the Geant4 version variable - If the version is incorrect, you will need to re-configure your build directory. If `cmake` isn't picking up the right Geant4 version by default, ensure that the `CMAKE_PREFIX_PATH` is pointing to your version of Geant4 - Make sure that your version of Geant4 was built with multithreading disabled @@ -216,8 +212,90 @@ mostly the same datasets, it is easier just to have each Geant4 version have its own downloaded copies of the datasets. ~~~ +## Running with your Geant4 +The way we use different versions of Geant4 has changed over the years, so it depends on which version of the image you are using. + +### >=5.1.0 +Since we are using `denv` to interact with the development image, you now have access to a local file that +can customize your development environment within the container image. +This file is `.profile` located within the container's home directory. +To find the location of this file, run +```sh +denv printenv HOME +``` +from the location where you want to use the custom Geant4. +The path output by this command is where the `.profile` is that you will edit. + +~~~admonish warning title="System `.profile`", collapsible=true +The `.profile` file is a file that exists in many normal Linux (and MacOS) systems. +I am just pointing this out because if you edit your system one (located at `~/.profile`) +instead of the one that is located within the denv workspace, you will not get the changes +to the container environment you want _and_ you could break your system. +~~~ + +All this stuff should go at the _end_ of the `.profile` so that you are "updating" the default +environment. + +First, make sure to unset the image-specific versions of the Geant4 environment variables defining +the location of the data directories. +This list may not be complete depending on the version of Geant4 installed in the image, you can use +`denv printenv` to see the full list of environment variables within the container environment. +``` +unset G4NEUTRONHPDATA +unset G4LEDATA +unset G4LEVELGAMMADATA +unset G4RADIOACTIVEDATA +unset G4PARTICLEXSDATA +unset G4PIIDATA +unset G4REALSURFACEDATA +unset G4SAIDXSDATA +unset G4ABLADATA +unset G4INCLDATA +unset G4ENSDFSTATEDATA +unset G4NEUTRONXSDATA +``` +If you changed the location of the data directory when building Geant4, make sure to also use that +location here by defining `GEANT4_DATA_DIR` _before_ sourcing the Geant4 environment script. +``` +# only needed if changed data location when building geant4 +export GEANT4_DATA_DIR=/full/path/to/custom/data/location +``` +Then source the custom Geant4's environment script. +``` +. /full/path/to/custom/geant4/bin/geant4.sh +# this stuff below is helpful to make sure a data directory is found +# and allows folks to have a debug build of Geant4 without re-downloading the data +# it goes _after_ the script because the script will define GEANT4_DATA_DIR if the +# build is configured with a specific data location +if [ -z "${GEANT4_DATA_DIR+x}" ]; then + export GEANT4_DATA_DIR="${G4DATADIR}" +fi +``` +And finally, update `CMAKE_PREFIX_PATH` so that ldmx-sw will prefer this custom Geant4 instead +of the one installed within the image. +``` +export CMAKE_PREFIX_PATH="/full/path/to/custom/geant4/lib/cmake:${CMAKE_PREFIX_PATH}" +``` + +After these changes, you should be able to compile and run ldmx-sw from this environment using +your custom build of Geant4 with the normal development commands. +``` +just compile +just fire config.py +``` + +You can make sure your Geant4 was found and is being used by going into the build and inspecting +the configuration. +``` +cd build && denv ccmake . +``` +You should see `Geant4_DIR` set to the path of your custom Geant4 instead of some path in `/usr/local/...`. + -### Running with your Geant4 +### <5.1.0,>=4.2.0 +With release 4.2.0 of the ldmx/dev image, the entrypoint script now checks the environment variable `LDMX_CUSTOM_GEANT4` for a path to a local installation of Geant4. +This allows the user to override the Geant4 that is within the image with one that available locally. In this way, you can choose whichever version of Geant4 you want, +with whatever code modifications applied, with whatever build instructions you choose. Just like with ldmx-sw, you can only run a specific build of Geant4 in the same image that you used to build it. ``` shell just setenv LDMX_CUSTOM_GEANT4=/path/to/geant4/install From f3d97c4e53bc4ccbe11894cd22da179885b9bdbf Mon Sep 17 00:00:00 2001 From: tomeichlersmith Date: Thu, 7 Aug 2025 10:24:35 -0500 Subject: [PATCH 8/9] move base definition of CMAKE_PREFIX_PATH into Dockerfile --- Dockerfile | 5 ++--- ldmx-env-init.sh | 2 -- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/Dockerfile b/Dockerfile index 2e554cc..593c966 100644 --- a/Dockerfile +++ b/Dockerfile @@ -449,7 +449,6 @@ RUN update-ca-certificates # copy environment initialization script into container # and make sure the default profile will call it as well +ENV CMAKE_PREFIX_PATH=/usr/local COPY ./ldmx-env-init.sh /etc/ -RUN printf "%s\n" \ - ". /etc/ldmx-env-init.sh" \ - >> /etc/skel/.profile +RUN printf "\n%s\n" ". /etc/ldmx-env-init.sh" >> /etc/skel/.profile diff --git a/ldmx-env-init.sh b/ldmx-env-init.sh index 2534061..732f289 100644 --- a/ldmx-env-init.sh +++ b/ldmx-env-init.sh @@ -28,8 +28,6 @@ if [ -z "${LDMX_SW_INSTALL+x}" ]; then fi fi -export CMAKE_PREFIX_PATH="/usr/local/" - if [ -n "${LDMX_SW_INSTALL+x}" ]; then export LD_LIBRARY_PATH="${LDMX_SW_INSTALL}/lib:${LD_LIBRARY_PATH}" export PYTHONPATH="${LDMX_SW_INSTALL}/python:${LDMX_SW_INSTALL}/lib:${PYTHONPATH}" From 37aa82f86addf567e9fbfbbb914a9ee50c579b53 Mon Sep 17 00:00:00 2001 From: tomeichlersmith Date: Fri, 8 Aug 2025 09:26:50 -0500 Subject: [PATCH 9/9] reread and fixup custom geant4 instructions --- docs/src/SUMMARY.md | 2 +- docs/src/custom-geant4.md | 34 ++++++++++++++++++++++------------ 2 files changed, 23 insertions(+), 13 deletions(-) diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index b07f52a..e658c14 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -3,10 +3,10 @@ [Welcome](README.md) # Using +- [Determing an Image's Version](image-version.md) - [Custom Geant4](custom-geant4.md) - [Custom Acts](custom-acts.md) - [Parallel Containers](parallel_containers.md) -- [Determing an Image's Version](image-version.md) # Developing - [Contributing](contributing.md) diff --git a/docs/src/custom-geant4.md b/docs/src/custom-geant4.md index bebf21a..2d0b509 100644 --- a/docs/src/custom-geant4.md +++ b/docs/src/custom-geant4.md @@ -8,7 +8,7 @@ Make sure you have an image that is at least v4.2.0. You can check your version of the image by [inspecting the image labels](image-version.md). ~~~ -### Building Your Geant4 +## Building Your Geant4 You can build your Geant4 in a similar manner as ldmx-sw. It does take much longer to compile than ldmx-sw since it is larger, so be sure to leave enough time for it. ```admonish warning title="Remember" @@ -16,7 +16,7 @@ You can only run this custom build of Geant4 with whatever image you are buildin ``` ``` shell -cd path/to/ldmx # directory that contains ldmx-sw +cd path/to/ldmx/ldmx-sw # ldmx-sw you want to build with custom geant4 git clone git@github.com:LDMX-Software/geant4.git # or could be mainline Geant4 or an unpacked tar-ball denv cmake -B geant4/build -S geant4 denv cmake --build geant4/build --target install @@ -24,19 +24,20 @@ denv cmake --build geant4/build --target install Now building Geant4 from source has a lot of configuration options that can be used to customize how it is built. Below are a few that are highlighted for how we use containers and their interaction with the Geant4 build. -- `CMAKE_INSTALL_PREFIX`: This should be set to a path accessible from the container so that the programs within the container can read from and write to this directory. If the geant4 build directory is within `LDMX_BASE` (like it is above), then you could do something like `-DCMAKE_INSTALL_PREFIX=../install` when you run `ldmx cmake` within the build directory. +- `CMAKE_INSTALL_PREFIX`: This should be set to a path accessible from the container so that the programs within the container can read from and write to this directory. If the geant4 build directory is within ldmx-sw (like it is above), then you could do something like `-DCMAKE_INSTALL_PREFIX=geant4/install` when you run `denv cmake ...` + - If you are keeping Geant4 outside of ldmx-sw, then you may need to mount it into the ldmx-sw container image with `denv config mounts` if it is not already within a mounted directory. - `GEANT4_INSTALL_DATADIR`: If you are building a version of Geant4 that has the same data files as the Geant4 version built into the container image, then you can tell the Geant4 build to use those data files with this option, saving build time and disk space. This is helpful if (for example) you are just re-building the same version of Geant4 but in Debug mode. You can see where the Geant4 data is within the container with `denv printenv G4DATADIR` and then use this value `-DGEANT4_INSTALL_DATADIR=/usr/local/share/geant4/data`. -The following are the build options used when setting up the container and are likely what you want to get started +The following are the build options used when setting up the image and are likely what you want to get started - `-DGEANT4_USE_GDML=ON` Enable reading geometries with the GDML markup language which is used in LDMX-sw for all our geometries - `-DGEANT4_INSTALL_EXAMPLES=OFF` Don't install the Geant4 example applications (just to save space and compilation time) - `-DGEANT4_USE_OPENGL_X11=ON` enable an X11-based GUI for inspecting geometries - `-DGEANT4_MULTITHREADED=OFF` If you are building a version of Geant4 that is multithreaded by default, you will want to disable it with. The dynamic loading used in LDMX-sw will often not work with a multithreaded version of Geant4 -#### Concerns when building different versions of Geant4 than 10.2.3 +### Concerns when building different versions of Geant4 than 10.2.3 -For most use cases you will be building a modified version of the same release of Geant4 that is used in the container (10.2.3). It is also possible to build and use later versions of Geant4 although this should be done with care. In particular -- Different Geant4 release versions will require that you rebuild LDMX-sw for use with that version, it will not be sufficient to set the `LDMX_CUSTOM_GEANT4` environment variable and pick up the shared libraries therein +For most use cases you will be building a modified version of the same release of Geant4 that is used in the image (10.2.3). It is also possible to build and use later versions of Geant4 although this should be done with care. In particular +- Different Geant4 release versions will require that you rebuild LDMX-sw for use with that version, it will not be sufficient to just source the custom Geant4's environment and pick up the shared libraries therein - Recent versions of Geant4 group the electromagnetic processes for each particle into a so-called general process for performance reasons. This means that many features in LDMX-sw that rely on the exact names of processes in Geant4 will not work. You can disable this by inserting something like the following in [RunManager::setupPhysics()](https://github.com/LDMX-Software/SimCore/blob/20d9bcb6d2bad2b99255cf32c1b3f099b26752b0/src/SimCore/RunManager.cxx#L60) ```C++ // Make sure to include G4EmParameters if needed @@ -45,9 +46,8 @@ auto electromagneticParameters {G4EmParameters::Instance()}; // i.e. G4GammaGeneralProcess and G4ElectronGeneralProcess electromagneticParameters->SetGeneralProcessActive(false); ``` -- Geant4 relies on being able to locate a set of datasets when running. For builds of 10.2.3, the ones that are present in the container will suffice but other versions may need different versions of these datasets. If you run into issues with this, use `ldmx env` and check that the following environment variables are pointing to the right location +- Geant4 relies on being able to locate a set of datasets when running. For builds of 10.2.3, the ones that are present in the container will suffice but other versions may need different versions of these datasets. If you run into issues with this, use `denv printenv` and check that the following environment variables are pointing to the right location - `GEANT4_DATA_DIR` should point to `$LDMX_CUSTOM_GEANT4/share/Geant4/data` - - You can define the `LDMX_CUSTOM_GEANT4_DATA_DIR` environment variable in the container environment to manually point it to a custom location - The following environment variables should either be unset or point to the correct location in `GEANT4_DATA_DIR` - `G4NEUTRONHPDATA` - `G4LEDATA` @@ -215,7 +215,7 @@ own downloaded copies of the datasets. ## Running with your Geant4 The way we use different versions of Geant4 has changed over the years, so it depends on which version of the image you are using. -### >=5.1.0 +### >=5.1.1 Since we are using `denv` to interact with the development image, you now have access to a local file that can customize your development environment within the container image. This file is `.profile` located within the container's home directory. @@ -226,7 +226,7 @@ denv printenv HOME from the location where you want to use the custom Geant4. The path output by this command is where the `.profile` is that you will edit. -~~~admonish warning title="System `.profile`", collapsible=true +~~~admonish warning title="System `.profile`" collapsible=true The `.profile` file is a file that exists in many normal Linux (and MacOS) systems. I am just pointing this out because if you edit your system one (located at `~/.profile`) instead of the one that is located within the denv workspace, you will not get the changes @@ -291,8 +291,18 @@ cd build && denv ccmake . ``` You should see `Geant4_DIR` set to the path of your custom Geant4 instead of some path in `/usr/local/...`. +~~~admonish note title="Returning to Normal" collapsible=true +If you want to return to the normal environment, you can comment-out or remove your `.profile` changes +at the bottom of that file. -### <5.1.0,>=4.2.0 +A nuclear option is to have the image re-copy of new `.profile` by removing the `.profile` file and a `denv` +internal file signalling that the profile has already been copied. +``` +rm .profile .denv/skel-init +``` +~~~ + +### <5.1.1,>=4.2.0 With release 4.2.0 of the ldmx/dev image, the entrypoint script now checks the environment variable `LDMX_CUSTOM_GEANT4` for a path to a local installation of Geant4. This allows the user to override the Geant4 that is within the image with one that available locally. In this way, you can choose whichever version of Geant4 you want, with whatever code modifications applied, with whatever build instructions you choose.