Tools and scripts reference

EPICS-env builds the Experimental Physics and Industrial Control System (EPICS) base and modules with make. The tools/ and scripts/ directories hold the programs around that build: checks of the installed tree, dependency and pin surveys, process variable (PV) helpers, and scripts that set up a shell for an installed tree. You run each Bash tool with bash. This command prints the usage of one tool:

bash tools/check_env.bash --help

audit_module_deps.bash without --top and check_deps.bash without an installed tree argument read make variables in the current directory; run them from the repository top. gen_dep_graph.bash, prep-vendors.bash, update-release.bash, and verify_fix_build.bash locate the checkout from their own path.

Programs in the tools directory

Placeholders in the Interface column:

• <installed_tree> is the installed tree for one host, the value of make print-INSTALL_LOCATION_EPICS.
• <repo> is the top directory of an EPICS-env checkout.
• <name> after --module is the lower-case module name, such as asyn.
• <pv_list> is a file with one PV name per line.

Behavior details of the tools

• audit_module_deps.bash reads the module list, each <module>_DEPS, and the AUDIT_* token lists through make print-<VARIABLE> in the directory that --top names. --platform defaults to the output of uname -s.

• check_deps.bash looks only in bin/linux-x86_64 and lib/linux-x86_64 under base and each module, and in vendor/lib. An RPATH or RUNPATH entry that starts with /usr/lib, such as /usr/lib64 or /usr/lib/x86_64-linux-gnu, prints a note and does not count as a finding.

• check_deps.bash resolves executable paths with realpath -e and removes duplicate canonical paths before calling readelf. Empty or non-directory tree paths and failed make lookups exit 2 with guidance to set INSTALL_LOCATION_EPICS or pass a valid <installed_tree>, including with --report-only.

• revert_patch.bash runs noninteractive GNU patch dry-runs before changing sources. For supported single-file, single-hunk patches, it checks that changed lines match the uniquely named static C function in the hunk header. Conflicting, partial, missing-input, and unresolved states fail with the source and patch identified. Both directions remaining valid is unresolved.

• Revert suppresses mismatch backups by default; --no-backup-if-mismatch accepts the same behavior explicitly. Existing target backups are preserved.

• Revert classification can copy real patch-owned source files into a private workspace. With --prerequisites, it supplies context from earlier patches there. For supported static C functions, a private patch adjusts only hunk search positions; GNU patch must match the contents inside the named function. Classification leaves the original source and shipped patches unchanged. Successful classification removes that workspace; failure retains it and prints its path. Fixed module targets pass no prerequisite list.

• pvs_gets.bash treats -f as a regular expression. -r appends .<field> to each PV name. -7 reads with pvget instead of caget. -c sets EPICS_CA_ADDR_LIST to the host’s Internet Protocol version 4 (IPv4) address and EPICS_CA_AUTO_ADDR_LIST to YES, or to NO together with -n.

• update-release.bash update offers four choices for each module whose pin differs from the latest release tag or branch head: keep the pin (the default), take the latest, enter a value, or exit. Choice 4 removes configure/RELEASE.new and exits 0 without writing configure/RELEASE.

• After the last module, update-release.bash update shows the difference and asks before it writes configure/RELEASE. It copies the replaced file to configure/RELEASE.bak.

• verify_fix_build.bash needs configure/MODULESGEN.mk in the checkout that holds it. It writes configure/RELEASE.local and configure/CONFIG_SITE.local in both copies. It keeps module-build.log, ioc-build.log, and the empty marker file .started in the parent directory of <module_dir>. It writes .started before the builds and fails when a file under the installed tree changes after that point.

• When the module dependencies of the checkout differ from those of the installed module, verify_fix_build.bash prints the difference and asks for confirmation on /dev/tty. Without a terminal, or on any answer other than y or Y, it exits 1.

• tc32-expansion-query.cpp has no make target. From the repository top, these commands build it against the uldaq library of an installed tree:

  VENDOR=<installed_tree>/vendor
  g++ -c -I"${VENDOR}/include" tools/tc32-expansion-query.cpp
  g++ -o tc32-expansion-query tc32-expansion-query.o -L"${VENDOR}/lib" -Wl,-rpath,"${VENDOR}/lib" -luldaq
  

  <installed_tree> is the installed tree, as in the table above. The second command compiles the source, and the third links the program in the current directory. The -Wl,-rpath option records the vendor library directory in the program as its RUNPATH, so it finds libuldaq.so at run time. The program and tc32-expansion-query.o stay in the repository top, and Git does not ignore them.

• prep-vendors.bash init empties ${HOME}/.vendor_temp_folder and writes configure/CONFIG_SITE.local. Vendor preparation writes that file in each vendor checkout. epics-env and epics-build rewrite configure/RELEASE.local with vendor paths and use the Network Time Protocol (NTP) default, time.google.com, from CONFIG_BASE.

• Before replacing an existing local configuration, prep-vendors.bash asks for confirmation when stdin is a terminal. It proceeds automatically when stdin is not a terminal. Both modes preserve a byte-identical backup as <file>.bak.<YYYYMMDDTHHMMSSZ>, using UTC and a numeric suffix on collision. Earlier backups remain unchanged. Backup failure, refusal, or EOF preserves the original and stops the invocation with status 1 before later build steps.

• The vendor builds use conf.rocky10 on Rocky 10, conf.rocky8 on Rocky 8, Red Hat Enterprise Linux (RHEL), CentOS, and Fedora, and conf elsewhere. all runs init, prep-vendors, and epics-env without a version argument.

Shell scripts in the scripts directory

<prefix> defaults to /usr/local. <base_version> is an EPICS base version, such as 7.0.10; build_epics.bash and install_apps.bash take it from make print-PATH_NAME_EPICSVERS. <os_id> and <os_version> are the ID and VERSION_ID values in /etc/os-release. <arch> is the value of EPICS_HOST_ARCH. setEpicsEnv.bash takes EPICS_HOST_ARCH from EpicsHostArch.pl under base/startup or base/lib/perl, or from base/startup/EpicsHostArch. It uses its argument as the architecture only when none of these files exists or perl is missing. A discovery command failure returns 1 before replacement. The argument disable suppresses the summary without becoming the architecture. Setup and reset are safe under set -u, compare complete path fields, and preserve independently configured CA settings. Select among installed versions by directly sourcing each chosen tree’s setup script. The selector’s legacy path differs from make’s <install_location>/<release>/<os_id>-<os_version>/<base_version> layout.

User configuration files for make

make user.conf copies the two files in configure_user/ into ${HOME}/configure, keeping a backup of any file it replaces. No EPICS-env make file reads the copies in ${HOME}/configure.

Build version record in site-template

make src_version writes site-template/.versions, holding the time it runs and the EPICS-env commit, and installs that file at the top of the installed tree. make src_clean removes site-template/.versions.