Template files

This document explains the role of the files commonly used in an EPNix IOC development.

Nix files

These files are generated by the nix flake new command.

flake.nix

This file is the entry point of Nix. Any Nix command, such as nix build or nix develop, reads this file first to figure out what to do.

Another way to see it, this is the Nix project file, like a pyproject.toml, or setup.py in Python, or package.json in Javascript. It defines the project’s “outputs”, in the case of the default template:

  • A package called default, which is the one used by nix build if no argument is given.

  • A check called simple. This check will be build by the nix flake check command. For more information, read Adding integration tests to your IOC.

  • An “overlay” called default. This can be used by external Nix projects for importing your package,

  • A NixOS module, defining how to integrate your IOC into a NixOS system. This module defines a systemd service that knows how to run your IOC. For more information, read IOC services.

ioc.nix

This file defines your EPICS package, which dependencies it has, how to compile it, and some metadata.

It may have:

  • the name of the package and its version,

  • the list of dependencies and their role during cross-compilation,

  • environment variables to set during the build

  • metadata such as the description, homepage, and license of your package

This file uses the mkEpicsPackage function, defined in the EPNix source code, which knows how to integrate and call the EPICS build system.

checks/simple.nix

This file defines the simple test exported in the flake.nix file.

It has:

  • the name of the test,

  • a definition of a NixOS virtual machine to run,

  • a test script in Python that runs commands on the virtual machine.

For an introduction to this file, read Adding integration tests to your IOC.

EPICS files

These files are generated by the makeBaseApp.pl command.

For an introduction on how to use these files, read Creating a StreamDevice IOC.

Makefile

This file is the entry point of the EPICS build system. The make command, which is used during the EPNix build, reads this file first to figure out what to do.

You can edit it to tell the build system which EPICS app depend on which other EPICS app.

exampleApp/

This folder is an EPICS app.

exampleApp/configure/RELEASE(.local)

These files are used by EPICS to find other EPICS dependencies, often called EPICS support modules.

The RELEASE.local file is managed by EPNix, and shouldn’t be added in your Git repository.

exampleApp/Db/

Use this folder to store EPICS database files, which defines the process variables that your IOC exposes.

exampleApp/src/Makefile

This Makefile defines how to compile your IOC program, and also generates a “database definition” file.

You can edit it to tell the EPICS build system what are your EPICS dependencies, and your library dependencies.

iocBoot/iocExample/st.cmd

This is an EPICS script that you use to start your IOC.

The commands in this file will tell which database to load, and which other operations to do on start.

It is often used to differentiate between to similar IOCs, for example controlling two similar power supplies, but on two different IP addresses, and with a different process variable prefix.