|
|
|
# Overview
|
|
|
|
This page walks a developer through setting up the environment for a build with a custom version of the RCG. The main command used for building real time models is the `rtcds build <model>` command, however some specific Linux env vars and `rtcds` vars need to be configured.
|
|
|
|
|
|
|
|
# Build Environment
|
|
|
|
In order for the `rtcds` command to be able to find your models, code etc. a few environment variables must be set.
|
|
|
|
|
|
|
|
### Listing the `rtcds` Build Environment
|
|
|
|
The environment can be listed by running the command:
|
|
|
|
```shell
|
|
|
|
controls@x1cymac:~$ rtcds env
|
|
|
|
SITE=TST
|
|
|
|
site=tst
|
|
|
|
IFO=X1
|
|
|
|
ifo=x1
|
|
|
|
RCG_SRC=/usr/share/advligorts/src
|
|
|
|
RTS_VERSION=5.0.0~devel
|
|
|
|
RCG_LIB_PATH=/home/controls/git/advligorts/test/:/usr/share/advligorts/src/src/epics/simLink/:/usr/share/advligorts/src/src/epics/simLink/lib
|
|
|
|
...
|
|
|
|
RCG_BUILD_ROOT=/var/cache/advligorts
|
|
|
|
RCG_BUILDD=/var/cache/advligorts/rcg-5.0.0~devel
|
|
|
|
RCG_TARGET=/opt/rtcds/tst/x1
|
|
|
|
CDS_SRC=/home/controls/git/advligorts/test/
|
|
|
|
CDS_IFO_SRC=/home/controls/git/advligorts/test/
|
|
|
|
...
|
|
|
|
```
|
|
|
|
It is important to note that this environment is being built up from multiple places, and ***not all variables are overridable***. For a complete listing checkout the [full build environment documentation](rtcds-Build-Environment-Variables)
|
|
|
|
|
|
|
|
<details>
|
|
|
|
<summary>Production Build Server Environment Example</summary>
|
|
|
|
|
|
|
|
```shell
|
|
|
|
(diskless)controls@h1build:~$ rtcds env
|
|
|
|
found host specific environment file '/etc/advligorts/systemd_env_h1build'
|
|
|
|
Build kernel-mode models by default
|
|
|
|
RTS_VERSION=4.2.8
|
|
|
|
SITE=LHO
|
|
|
|
IFO=H1
|
|
|
|
RCG_LIB_PATH=/opt/rtcds/userapps/release/als/h1/models:/opt/rtcds/userapps/release/als/common/models:/opt/rtcds/userapps/release/asc/h1/models:/opt/rtcds/userapps/release/asc/common/models:/opt/rtcds/userapps/release/cal/h1/models:/opt/rtcds/userapps/release/cal/common/models:/opt/rtcds/userapps/release/cds/h1/models:/opt/rtcds/userapps/release/cds/common/models:/opt/rtcds/userapps/release/hpi/h1/models:/opt/rtcds/userapps/release/hpi/common/models:/opt/rtcds/userapps/release/imc/h1/models:/opt/rtcds/userapps/release/imc/common/models:/opt/rtcds/userapps/release/ioo/h1/models:/opt/rtcds/userapps/release/ioo/common/models:/opt/rtcds/userapps/release/isc/h1/models:/opt/rtcds/userapps/release/isc/common/models:/opt/rtcds/userapps/release/isi/h1/models:/opt/rtcds/userapps/release/isi/common/models:/opt/rtcds/userapps/release/lsc/h1/models:/opt/rtcds/userapps/release/lsc/common/models:/opt/rtcds/userapps/release/omc/h1/models:/opt/rtcds/userapps/release/omc/common/models:/opt/rtcds/userapps/release/pem/h1/models:/opt/rtcds/userapps/release/pem/common/models:/opt/rtcds/userapps/release/psl/h1/models:/opt/rtcds/userapps/release/psl/common/models:/opt/rtcds/userapps/release/sqz/h1/models:/opt/rtcds/userapps/release/sqz/common/models:/opt/rtcds/userapps/release/sus/h1/models:/opt/rtcds/userapps/release/sus/common/models:/opt/rtcds/userapps/release/sys/h1/models:/opt/rtcds/userapps/release/sys/common/models:/opt/rtcds/userapps/release/tcs/h1/models:/opt/rtcds/userapps/release/tcs/common/models:/opt/rtcds/userapps/release/cds/test/models:/usr/share/advligorts/src/src/epics/simLink/:/usr/share/advligorts/src/src/epics/simLink/lib
|
|
|
|
RCG_SRC=/usr/share/advligorts/src
|
|
|
|
RCG_BUILD_ROOT=/opt/rtcds/rtbuild
|
|
|
|
RCG_BUILDD=/opt/rtcds/rtbuild/rcg-4.2.8
|
|
|
|
RCG_TARGET=/opt/rtcds/lho/h1
|
|
|
|
```
|
|
|
|
|
|
|
|
Note that the `RCG_LIB_PATH` is very long, pulling in all `h1` specific models.
|
|
|
|
</details>
|
|
|
|
|
|
|
|
### Setting the Build Environment
|
|
|
|
|
|
|
|
These paths assume you cloned advligorts into your home directory, you will need to adjust to the paths for the directory you chose.
|
|
|
|
|
|
|
|
```shell
|
|
|
|
export RTS_VERSION=cymac-build
|
|
|
|
export RCG_SRC=/home/$USER/advligorts/
|
|
|
|
export CDS_SRC=/home/$USER/advligorts/src/include/
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### Allowing `rtcds` to Find your Custom Model
|
|
|
|
In order for `rtcds` to find your model (the <model_name>.mdl file) the `RCG_LIB_PATH` env variable needs to have a path to the directory containing it. The best way to do that, is adding the directory path to the `RCG_LIB_PATH` line in the `/etc/advligorts/env` file.
|
|
|
|
|
|
|
|
If you have your custom model located at `/home/controls/models/` then you should add that path (colon (:) separated) to your env file.
|
|
|
|
|
|
|
|
After adding the line, your `/etc/advligorts/env` file might look like:
|
|
|
|
```shell
|
|
|
|
SITE=TST
|
|
|
|
IFO=X1
|
|
|
|
RCG_LIB_PATH=/home/controls/git/advligorts/test/:/home/controls/models/
|
|
|
|
```
|
|
|
|
Note the `RTS_ENV` environmental variable will override where `rtcds` looks for the env file, so if you want the default functionality make sure it is unset.
|
|
|
|
|
|
|
|
### Verification
|
|
|
|
You can list your `rtcds` environment again with the `rtcds env` command and your output after setting the version/src variables and editing the `/etc/advligorts/env` file will look something like:
|
|
|
|
```shell
|
|
|
|
controls@x1cymac:~$ rtcds env
|
|
|
|
...
|
|
|
|
...
|
|
|
|
RCG_SRC=/home/controls/advligorts/
|
|
|
|
RTS_VERSION=cymac-build
|
|
|
|
RCG_LIB_PATH=/home/controls/git/advligorts/test/:/home/controls/models/:/home/controls/advligorts//src/epics/simLink/:/home/controls/advligorts//src/epics/simLink/lib
|
|
|
|
...
|
|
|
|
RCG_BUILD_ROOT=/var/cache/advligorts
|
|
|
|
RCG_BUILDD=/var/cache/advligorts/rcg-cymac-build
|
|
|
|
RCG_TARGET=/opt/rtcds/tst/x1
|
|
|
|
CDS_SRC=/home/controls/advligorts/src/include/
|
|
|
|
CDS_IFO_SRC=/home/controls/advligorts/src/include/
|
|
|
|
...
|
|
|
|
...
|
|
|
|
```
|
|
|
|
While `rtcds` has appended some additional paths to the `RCG_LIB_PATH` variable, the path we added (`/home/controls/models/`) is present in the list. Now when we run `rtcds build <model_name>`, `rtcds` will look in `/home/controls/models/` for a file named `<model_name>.mdl`
|
|
|
|
|
|
|
|
# Building Custom Models (CyMAC Usecase)
|
|
|
|
Now that the environment has been set up, all we need to do is run the `rtcds build <model_name> ` command. Example output for building a model with the mdl filename of `x1unittest.mdl`:
|
|
|
|
```shell
|
|
|
|
controls@x1cymac:~/models$ rtcds build x1unittest
|
|
|
|
WARNING: RTS_VERSION=cymac-build does not match version found in source: local)
|
|
|
|
### building x1unittest
|
|
|
|
Cleaning x1unittest...
|
|
|
|
Done
|
|
|
|
Parsing the model x1unittest...
|
|
|
|
Done
|
|
|
|
Building EPICS sequencers...
|
|
|
|
Done
|
|
|
|
Building front-end Linux kernel module x1unittest...
|
|
|
|
Done
|
|
|
|
RCG source code directory:
|
|
|
|
/home/controls/git/advligorts
|
|
|
|
The following files were used for this build:
|
|
|
|
/home/controls/models//x1unittest.mdl
|
|
|
|
|
|
|
|
Successfully compiled x1unittest
|
|
|
|
***********************************************
|
|
|
|
Compile Warnings, found in /var/cache/advligorts/rcg-cymac-build//models/x1unittest/logs/x1unittest_warnings.log:
|
|
|
|
***********************************************
|
|
|
|
***********************************************
|
|
|
|
```
|
|
|
|
|
|
|
|
### Build Output
|
|
|
|
Build products are stored in `$RCG_BUILDD/models/<model_name>`. Note that `RCG_BUILDD` is not a Linux env variable, so you will have to view it with `rtcds env` and navigate to the displayed path.
|
|
|
|
|
|
|
|
Starting with RCG version 5.0+ the structure of the RCG_BUILDD has changed, and is now more modular/intuitive. If you are used to older versions, this output will look different.
|
|
|
|
|
|
|
|
For our example the build products are stored in `/var/cache/advligorts/rcg-cymac-build//models/x1unittest`. Doing a tree of that directory the following structure is observed:
|
|
|
|
```shell
|
|
|
|
controls@x1cymac:~$ tree -L 1 /var/cache/advligorts/rcg-cymac-build/models/x1unittest/
|
|
|
|
/var/cache/advligorts/rcg-cymac-build/models/x1unittest/
|
|
|
|
├── epics
|
|
|
|
├── include
|
|
|
|
├── kernel_mod
|
|
|
|
├── logs
|
|
|
|
├── target
|
|
|
|
└── userspace
|
|
|
|
```
|
|
|
|
#### Explanation
|
|
|
|
| Directory | Used For |
|
|
|
|
| --------- | --------- |
|
|
|
|
| `epics/` | Stores the generated EPICS process that is built alongside the kernel module |
|
|
|
|
| `include/` | Contains shared header files for the Kernel module and EPICS process |
|
|
|
|
| `kernel_mod/` | This has the kernel module build scrips and kernel space generated real time model code|
|
|
|
|
| `logs/` | Contains log file from the various parts of the model build |
|
|
|
|
| `target/` | Mirrors what the model will look like when it is install on the system. This stores the kernel module `.ko` EPICS process and configuration and information about the env/code that was used to build.
|
|
|
|
| `userspace/` | Stores the userspace build scrips and generated model code |
|
|
|
|
|
|
|
|
# Next Steps
|
|
|
|
If you are trying to run the module you just build, go to the [Installing Built Models](Installing-Modules) page. |
|
|
\ No newline at end of file |
