assemble_synApps

synApps assemble script

Used to pull a user-defined set of EPICS modules at given tags and package them into a single synApps directory that will build with a single make command.

Prerequisites

• Perl 5.12 or later
• Git
• curl (for downloading AllenBradley, ULDAQ, and open62541 tarballs)
• make and a C/C++ compiler (for building ULDAQ and open62541 on Linux)
• A built EPICS base installation
• cmake, python3, libssl-dev, libxml2-dev (for building open62541, only needed when OPCUA is enabled without a Unified Automation SDK)

Quick Start

# Clone the assemble script
git clone https://github.com/EPICS-synApps/assemble_synApps.git
cd assemble_synApps

# Assemble synApps using the default module set
./assemble_synApps --base=/path/to/epics/base

# Build synApps
cd git/support
make -j4

Command Line Options

./assemble_synApps [options]

Option	Description
--base=<path>	Path to a built EPICS base installation
--config=<file>	Use an external config file instead of the default module list
--dir=<name>	Name of the output directory (default: git)
--set MODULE=TAG	Override a single module's tag (repeatable)
--update	Skip modules already at the correct tag
--check	Display module list without downloading
--quiet	Suppress progress messages and external tool output
--verbose	Show full output from git and other external commands
--help	Print usage information

base

The base option defines the location of the EPICS base installation that synApps will link against. The path must point to a fully built EPICS base directory (containing include/epicsVersion.h).

./assemble_synApps --base=/APSshare/epics/base-7.0.8

config

The config option provides a separate file with a list of modules and their tags. The file should have one definition per line in the form MODULE_NAME=module_tag.

# myconfig.txt
ASYN=R4-44-2
AUTOSAVE=R5-11
BUSY=R1-7-4
CALC=R3-7-5
SSCAN=R2-11-6
DEVIOCSTATS=3.1.16
SNCSEQ=R2-2-9
STD=R3-6-4
STREAM=2.8.24
XXX=R6-3

./assemble_synApps --base=/path/to/base --config=myconfig.txt

Config file definitions completely replace the default module list. If a module is not listed in the config file, it will not be downloaded. Blank lines and lines starting with # are ignored. Leading and trailing whitespace around keys and values is trimmed.

dir

The dir option defines the name of the synApps directory to be created. All modules will be downloaded into <dir>/support/.

./assemble_synApps --base=/path/to/base --dir=synApps_R6-3
# Creates synApps_R6-3/support/

The default directory name is git.

set

The set option makes individual changes to the module definitions. Each usage should be followed by a string in the form MODULE_NAME=module_tag. These definitions will either create a new entry or overwrite an existing one. This works with both the default module list and a config file.

# Override specific module versions
./assemble_synApps --base=/path/to/base \
    --set ASYN=R4-45 \
    --set MOTOR=R7-3-1

# Remove a module by setting its tag to an empty string
./assemble_synApps --base=/path/to/base --set GALIL= --set DXP=

# Add extra areaDetector submodules (space-separated list)
./assemble_synApps --base=/path/to/base \
    --set "AREA_DETECTOR_SUBMODULES=ADProsilica ADPointGrey ADPilatus"

latest

Any repository module can be set to latest (case-insensitive) to automatically track its default branch, regardless of whether the repo uses main, master, or another name. The script resolves latest to the actual default branch via git ls-remote before cloning, so folder names and RELEASE paths reflect the real branch (e.g., calc-master, sequencer-main).

# Resolve individual modules to their default branch
./assemble_synApps --base=/path/to/base --set SNCSEQ=latest --set CALC=latest

# Use in a config file
# myconfig.txt:
#   CALC=latest
#   SNCSEQ=latest
#   SSCAN=latest
./assemble_synApps --base=/path/to/base --config=myconfig.txt

Notes:

• latest is only meaningful for repository modules. Setting it on keys that are downloaded with curl (OPEN62541, UASDK, ULDAQ, ALLENBRADLEY) produces a warning and leaves the value unchanged.
• If a repository actually has a branch or tag named latest, that real ref is used as-is rather than resolving to the default branch.

update

The update option skips modules that are already cloned at the correct tag. This is useful for two scenarios:

Resuming after a failure: If the script fails partway through (e.g., a network error during cloning), re-running with --update will skip the modules that were already successfully cloned and pick up where it left off.

# Initial run fails partway through
./assemble_synApps --base=/path/to/base
# ... network error on module 20 of 40 ...

# Resume -- skips the first 19 modules
./assemble_synApps --base=/path/to/base --update

Adding modules to an existing deployment: If you have a working synApps and want to add a new module or change one module's version, --update avoids re-cloning and re-patching all the unchanged modules.

# Add a new module to an existing synApps
./assemble_synApps --base=/path/to/base --set OPCUA=v0.11.2 --update

# Change one module's version
./assemble_synApps --base=/path/to/base --set ASYN=R4-45 --update

When --update is set:

• Modules already at the requested tag are skipped entirely (no git clean, no re-patching).
• Modules at a different tag are updated to the new tag and re-patched.
• New modules not yet cloned are cloned and patched normally.
• The configure/RELEASE file is always regenerated to ensure consistency.
• AllenBradley is skipped if its directory already exists.
• The ULDAQ library build (inside measComp) is skipped if already built.
• The open62541 library download (inside OPCUA) is skipped if already present.

Without --update, the script restores every existing module to a clean state (git stash, git clean -fdx, git checkout) and re-applies all patches. This is the default behavior and ensures a fully clean assembly.

check

The check option is a dry run. It displays the module definitions that would be used without downloading anything.

./assemble_synApps --base=/path/to/base --check

quiet / verbose

These options control the amount of output produced by the script.

• --quiet suppresses progress messages ("Grabbing X at tag Y") and redirects stdout from external tools (git, curl, tar, make) to /dev/null. Errors and warnings are always shown on stderr.

• --verbose shows full output from git commands (removes the default -q flag). All progress messages are shown.

These flags are mutually exclusive.

# Silent operation -- only errors/warnings shown
./assemble_synApps --base=/path/to/base --quiet

# Full git output for debugging
./assemble_synApps --base=/path/to/base --verbose

Re-running the Script

The script can be safely re-run against an existing synApps directory:

• The support/ repository is not re-cloned if it already exists.
• Without --update, each module is restored to a clean state and all patches are re-applied. This wipes any local changes or build artifacts in module directories.
• With --update, only new or changed modules are touched. Existing modules at the correct tag are left as-is, preserving build artifacts.
• The configure/RELEASE file is always regenerated from scratch.
• make release is run at the end to propagate paths to all modules.

Examples

# Basic assembly with default modules
./assemble_synApps --base=/usr/local/epics/base-7.0.8

# Custom directory name
./assemble_synApps --base=/path/to/base --dir=synApps_R6-3

# Minimal synApps using a config file
./assemble_synApps --base=/path/to/base --config=minimal.txt

# Remove modules you don't need
./assemble_synApps --base=/path/to/base --set GALIL= --set DXP= --set XSPRESS3=

# Preview what would be assembled
./assemble_synApps --base=/path/to/base --set ASYN=R4-45 --check

# Quiet assembly for CI/automated builds
./assemble_synApps --base=/path/to/base --quiet

# Resume a failed assembly
./assemble_synApps --base=/path/to/base --update

# Add a module to an existing deployment
./assemble_synApps --base=/path/to/base --set OPCUA=v0.11.2 --update

# Use the Unified Automation SDK instead of open62541 for OPCUA
./assemble_synApps --base=/path/to/base --set UASDK=/opt/opcua/sdk

OPCUA Module

The OPCUA module supports two mutually exclusive OPC UA client SDK backends:

• open62541 (default) -- open-source, built from source automatically by the script. Set the OPEN62541 key to a version tag (e.g., v1.3.15). The library is downloaded, built with CMake inside the opcua module directory, and configured in EMBED mode (statically linked into libopcua). Requires cmake, python3, libssl-dev, and libxml2-dev on the build host.

• Unified Automation SDK (UASDK) -- a commercial, pre-installed SDK. Set the UASDK key to the filesystem path of an existing SDK installation (e.g., /opt/opcua/uasdkcppclient-v1.5.3/sdk). The script configures OPCUA in PROVIDED mode; no download or build is performed for the SDK itself.

SDK selection rule: If UASDK is defined and the directory exists, the module is configured for the Unified Automation SDK. Otherwise, the script falls back to downloading and building open62541. If a UASDK path is set but does not exist, a warning is printed and open62541 is used.

# Default: uses open62541 v1.3.15
./assemble_synApps --base=/path/to/base

# Specify a different open62541 version
./assemble_synApps --base=/path/to/base --set OPEN62541=v1.3.12

# Use the Unified Automation SDK
./assemble_synApps --base=/path/to/base --set UASDK=/opt/opcua/sdk

# Disable OPCUA entirely
./assemble_synApps --base=/path/to/base --set OPCUA=