Module Management

Scope

This document defines the module naming, dependency declaration, configure type declaration, and validation conventions used by the EPICS-env Makefile system.

Out of scope: operator commands for adding a module are covered in Add a Module. Module-specific patches and external vendor setup are covered by each module’s existing configuration rules.

Data Flow

Module metadata flows through the build system in this order.

configure/RELEASE declares SRC_NAME_*, SRC_TAG_*, and SRC_VER_*.
configure/CONFIG_MODS generates configure/MODULESGEN.mk and SRC_PATH_MODULES.
configure/CONFIG_MODS_DEPS declares <module>_DEPS and <module>_CONF_TYPE.
configure/RULES_FUNC derives generated target names from SRC_PATH_MODULES.
configure/RULES_MODS_CONF_AUTO generates conf.* and conf.*.show targets for auto modules.
configure/RULES_MODS_CONFIG keeps explicit conf.* and conf.*.show targets for custom modules.

The module key used in CONFIG_MODS_DEPS must match the generated build target key. The key is derived from SRC_PATH_MODULES by removing a trailing -src path component and by reducing recsync-src/client to recsync.

$(patsubst %-src,%, $(patsubst %/client, %, $(dir)))

The sequencer module has three names in the system.

Layer	Name
Source module name	`sequencer`
Generated build target	`build.sequencer`
Installed module symlink	`seq`

The dependency key is therefore sequencer_DEPS, not sncseq_DEPS or seq_DEPS.

Build Dependency Declarations

Each module declares its build prerequisites with <module>_DEPS.

asyn_DEPS:=null.base build.sequencer build.sscan build.calc

The prerequisite order is significant because it becomes the prerequisite order of the generated build.<module> target.

Modules with only EPICS Base as a prerequisite use null.base.

pcas_DEPS:=null.base

Configure Type Declarations

Each module declares exactly one configure type.

Type	Meaning
`auto`	Configuration needs only `INSTALL_LOCATION` and simple local flags.
`custom`	Configuration needs module paths, vendor paths, source edits, or special files.

Current behavior: auto modules use generated conf.* and conf.*.show rules. custom modules remain hand-written in configure/RULES_MODS_CONFIG.

The generated rule writes INSTALL_LOCATION to CONFIG_SITE.local and optionally writes module-specific simple lines declared in configure/CONFIG_MODS_DEPS.

Global Module Settings

conf.release.modules writes the repository-level CONFIG_SITE.local before module configuration runs. That file provides settings that apply to modules whose upstream configure/CONFIG_SITE includes $(TOP)/../CONFIG_SITE.local.

CHECK_RELEASE = NO
PROD_LDFLAGS += -Wl,--enable-new-dtags

Do not duplicate these global settings in generated auto-module declarations. For example, pscdrv inherits CHECK_RELEASE = NO through its upstream configure/CONFIG_SITE, so pscdrv_CONF_SITE_LINES must not restate it.

Module-local CHECK_RELEASE = NO belongs only in explicit custom rules that rewrite configure/CONFIG_SITE, remove the upstream include path, or need a module-specific override that is not provided by the repository-level local file.

Current Classification

`auto`	`custom`
`MCoreUtils`	`asyn`
`autosave`	`busy`
`caPutLog`	`calc`
`ether_ip`	`linStat`
`iocStats`	`lua`
`pcas`	`mca`
`pscdrv`	`measComp`
`retools`	`modbus`
`snmp`	`motor`
	`motorMotorSim`
	`opcua`
	`pmac`
	`pvxs`
	`recsync`
	`scaler`
	`sequencer`
	`sscan`
	`std`
	`StreamDevice`

Validation

CONFIG_MODS_DEPS validates configure type declarations at Make parse time. Every module derived from SRC_PATH_MODULES must declare <module>_CONF_TYPE, and the value must be either auto or custom.

define validate_conf_type
$(if $($(1)_CONF_TYPE),,$(error Missing $(1)_CONF_TYPE declaration))
$(if $(filter auto custom,$($(1)_CONF_TYPE)),,$(error Invalid $(1)_CONF_TYPE value: $($(1)_CONF_TYPE)))
endef

This makes missing declarations and spelling errors fail before any module configuration or build recipe runs.

Maintenance Rules

When adding or renaming a module, keep these declarations aligned.

SRC_NAME_* defines the source repository name.
SRC_PATH_MODULES defines the generated module key.
<module>_DEPS must use the generated module key.
<module>_CONF_TYPE must use the generated module key.
auto modules get generated conf.* rules.
custom modules must keep explicit conf.* rules in RULES_MODS_CONFIG.
A custom module’s conf.* target joins MODS_ZERO_CUSTOM_VARS or MODS_ONE_VARS. MODS_ZERO_VARS is derived from MODS_ZERO_CUSTOM_VARS plus the generated auto targets and is never an edit point; replacing it with a literal list drops every auto module’s configure target.

Changing how these lists are built also changes what the operator guides describe. The guides that name them are Add a Module, Worked Example: Add pmac, and Remove a Module; check all three against the change.

EPICS Configuration Environment (EPICS-env)