diff --git a/2-IOC-deployment.md b/2-IOC-deployment.md
index 2cd25c8823b8095bad609e46ed941e09ee1eb8a4..2e3c09345d110d8579624697a2a0bca4f30dbaba 100644
--- a/2-IOC-deployment.md
+++ b/2-IOC-deployment.md
@@ -115,6 +115,24 @@ configure/CONFIG:18: *** EPICS_BASE must be set in a configure/RELEASE file. St
```
</details>
+<details>
+<summary>what does this mean?</summary>
+
+This error message indicates that the `EPICS_BASE` environment variable is not defined in your **configure/RELEASE** file.
+
+`EPICS_BASE` is a mandatory environment variable that points to the location of the EPICS base installation directory. The **configure/RELEASE** file is used to define EPICS-related environment variables required for building an IOC.
+
+Here's an example of how to set the `EPICS_BASE `variable in the **configure/RELEASE** file:
+
+```
+EPICS_BASE=/path/to/epics/base
+```
+
+where "/path/to/epics/base" points to your EPICS base installation directory.
+
+Once you have set the `EPICS_BASE` variable in the **configure/RELEASE** file, try building your IOC again and the error should be resolved.
+</details>
+
### 2.5 Resolve build error #1
Modify **configure/RELEASE** so that ``EPICS_BASE`` is defined.
@@ -125,7 +143,7 @@ $ gedit configure/RELEASE &
<details>
<summary>solution</summary>
-EPICS_BASE doesn't need to be defined explicitly; The synApps configure/RELEASE file defines the version of base used to build it, so only the SUPPORT path needs to be corrected.
+`EPICS_BASE` doesn't need to be defined explicitly; the synApps configure/RELEASE file defines the version of base used to build it, so only the SUPPORT path needs to be corrected.
```diff
$ git diff
@@ -146,6 +164,19 @@ $
```
</details>
+<details>
+<summary>what does this mean?</summary>
+
+We are using the 6.2.1 release of synApps, which is a collection of EPICS modules that are deployed and tested at the APS. The ``SUPPORT`` variable is defined to point to the directory where the synApps support modules are installed:
+**/APSshare/epics/synApps_6_2_1/support**.
+
+The ``-include`` directive is used to include the **configure/RELEASE** file from the synApps support module directory, which sets various EPICS-related environment variables, including ``EPICS_BASE``, as needed for building the IOC.
+
+Therefore, we do not need to explicitly set the ``EPICS_BASE`` variable in your **configure/RELEASE** file because it is already set in the synApps support module's **configure/RELEASE** file.
+
+Note: The ``include`` directive specifies a required file; an error occurs if the file doesn't exist. The ``-include`` directive specifies an optional file that is included if it exists and ignored if it doesn't.
+</details>
+
### 2.6 Build the IOC (attempt #2)
If following the build succeeds, skip to step 2.9
@@ -173,6 +204,14 @@ make: *** [xxxApp.install] Error 2
```
</details>
+<details>
+<summary>what does this mean?</summary>
+
+This error message indicates that the linker (ld) is unable to find two libraries: net and pcap. When building your IOC using the make command, the linker is responsible for resolving and linking all the required libraries.
+The -l flag is used to specify libraries that need to be linked. In this case, the linker is looking for net and pcap. However, it is unable to locate these libraries, which results in the error.
+
+</details>
+
### 2.7 Resolve build error #2
Tell the build system the net (and pcap) libraries aren't installed.
@@ -180,10 +219,20 @@ Tell the build system the net (and pcap) libraries aren't installed.
```
$ echo "LINUX_NET_INSTALLED = NO" > configure/CONFIG_SITE.local
```
+<details>
+<summary>what does this mean?</summary>
+
+The **configure/CONFIG_SITE.local** file is used to specify local configuration settings for building an EPICS IOC. By setting ``LINUX_NET_INSTALLED`` to ``NO``, you are disabling the use of the net library by telling the build system that this library is not installed on your system, which was causing the linker errors.
+
+The IOC build system will now use an alternative networking library instead of libnet, allowing the IOC to be built without requiring the installation of the net library.
+
+**Note:** the linux command ``$ echo "LINUX_NET_INSTALLED = NO" > configure/CONFIG_SITE.local`` writes the text "LINUX_NET_INSTALLED = NO" to the **configure/CONFIG_SITE.local** file. If the file does not exist, the ``>`` sign creates the file and writes the output to it. If the file already exists, behavior is dependent on which shell is used. For bash, the ``>`` sign overwrites its contents with the new output. For tcsh, the ``>`` sign results in an error because the file already exists.
+
+</details>
### 2.8 Build the IOC
-We do a clean build at this point to ensure the fix for the previous failed build takes effect. The value that was set in in `CONFIG_SITE.local` causes some software to be exluded from the IOC. Without the `make distclean` the excluded software can be partially included in the IOC, which results in build problems.
+We do a clean build at this point to ensure the fix for the previous failed build takes effect. The value that was set in `CONFIG_SITE.local` causes some software to be exluded from the IOC. Without the `make distclean` the excluded software can be partially included in the IOC, which results in build problems.
```
$ make distclean
@@ -267,6 +316,14 @@ perl -CSD /APSshare/epics/base-7.0.4.1/bin/rhel8-x86_64/convertRelease.pl -t /ho
```
</details>
+<details>
+<summary>what does this mean?</summary>
+
+Perl is a programming language commonly used for scripting and text processing. The command is essentially invoking the convertRelease.pl script and passing the path to the IOC's top-level directory as an argument. The script will process the IOC's configure/RELEASE file and use the contents to create the envPaths file.
+
+</details>
+
+
#### 2.10.4 Run the IOC
Start the IOC and confirm the error is resolved.
diff --git a/3-Add-simulated-motors.md b/3-Add-simulated-motors.md
index b015da773a98fb0138f93cf90e163de23948f2e6..4a4bae6e4e56c3afd3d38fce9251989001570635 100644
--- a/3-Add-simulated-motors.md
+++ b/3-Add-simulated-motors.md
@@ -56,6 +56,12 @@ index 34998d9..273bea4 100644
```
</details>
+<details><summary>what does this mean?</summary>
+
+The `motorSim.iocsh` script will be loaded when the `motors.iocsh` script is run, and the controller instance defined in the `motorSim.iocsh` script will be set up with the specified parameters (instance name, home position, number of axes, high and low limits, and substitution definitions). This is useful for running a simulation of your motor system for testing or development purposes.
+
+</details>
+
#### 3.2.2 Edit substitutions/motorSim.substitutions
```
@@ -140,6 +146,16 @@ index 588dda7..8fddfc1 100644
```
</details>
+
+<details>
+<summary>what does this mean?</summary>
+
+The `st.cmd.Linux` file is the IOC startup script which is responsible for initializing the EPICS environment, loading database definitions, and starting the IOC.
+The command `< iocsh/motors.iocsh` is used to execute the `motors.iocsh` script in the current shell environment.
+After you make this modification and run the startup script, it will execute the commands in `motors.iocsh` as part of the IOC startup process, setting up the motor instance as specified in the `motors.iocsh` file.
+
+</details>
+
### 3.3 Run the IOC
Start the IOC in a screen session:
@@ -198,6 +214,14 @@ Confirm that motor settings are being saved
```
$ grep motor autosave/built_*.req
```
+
+<details>
+<summary>what does grep mean?</summary>
+
+The command `grep motor autosave/built_*.req` searches for the string "motor" within the contents of files that match the pattern **autosave/built_*.req**.
+
+</details>
+
<details>
<summary>output</summary>
@@ -221,6 +245,8 @@ autosave/built_settings.req:file asyn_motor_settings.req P=kmp:,N=8,M="m8",DTYP=
```
</details>
+
+
### 3.4 Launch motor screen
Do the following:
diff --git a/4-Deploy-motorVMC.md b/4-Deploy-motorVMC.md
index 1b2b4754265f8b931ea48cb4d2f7f52b7c624e07..3ff4a27ddb0863573b3e1070b3912f64e4925e93 100644
--- a/4-Deploy-motorVMC.md
+++ b/4-Deploy-motorVMC.md
@@ -73,6 +73,7 @@ make: *** No rule to make target '/configure/RULES_TOP'. Stop.
```
</details>
+
### 4.4 Resolve build error #1
This build error occurs for the same reason the build error occurred in [step 2.4](2-IOC-deployment.md#24-build-the-ioc-attempt-1): `EPICS_BASE` isn't defined.
@@ -82,10 +83,19 @@ The error was much more helpful in step 2.4 because [xxx's CONFIG file prints th
<details>
<summary>hint</summary>
+The **motorVMC/README.md** file indicates:
+
+```
+The definitions of `MOTOR` and `EPICS_BASE` need to be corrected in `motorVMC/configure/RELEASE` before motorVMC can be built.
+```
+
The **motorVMC/configure/RELEASE** file doesn't contain any definitions, but it does include other files **if they exist**.
+
+
</details>
+
<details>
<summary>solution</summary>
@@ -93,9 +103,9 @@ The **motorVMC/configure/RELEASE** file doesn't contain any definitions, but it
$ cp -p configure/EXAMPLE_RELEASE.local configure/RELEASE.local
```
-The RELEASE.local file contains two variables that need be defined: `MOTOR` and `MOTOR_VMC`
+The **RELEASE.local** file contains two variables that need be defined: `MOTOR` and `MOTOR_VMC`
-`MOTOR` should be set to the same path that is in the envPaths file:
+`MOTOR` should be set to the same path that is in the **envPaths** file:
```
$ grep MOTOR ${IOC_DIR}/xxx/iocBoot/iocxxx/envPaths
@@ -120,6 +130,90 @@ MOTOR_VMC=/home/beams/USERNAME/PET-S2/epics/synApps/support/motorVMC
```
</details>
+
+<details>
+<summary>where is EPICS_BASE defined?</summary>
+
+The `EPICS_BASE` variable is not explicitly defined: it is defined in the motor
+configuration file that is included with on line 2 of the **configure/RELEASE.local**:
+
+```
+$ cat ${MOTOR}/modules/RELEASE.${EPICS_HOST_ARCH}.local
+MOTOR = /net/aquila/export/APSmaster/gateway/epics/synApps_6_2_1/support/motor-R7-2-2
+ASYN = /APSshare/epics/synApps_6_2_1/support/asyn-R4-42
+SNCSEQ = /APSshare/epics/synApps_6_2_1/support/seq-2-2-9
+BUSY = /APSshare/epics/synApps_6_2_1/support/busy-R1-7-3
+IPAC = /APSshare/epics/synApps_6_2_1/support/ipac-2-16
+LUA = /APSshare/epics/synApps_6_2_1/support/lua-R3-0-2
+EPICS_BASE = /APSshare/epics/base-7.0.4.1
+SUPPORT = /APSshare/epics/synApps_6_2_1/support
+```
+</details>
+
+<details>
+<summary>what is the difference between RELEASE and RELEASE.local?</summary>
+
+In the motorVMC module's configure folder, the presence of two **RELEASE** files,
+**RELEASE** and **RELEASE.local**, allows for two levels of configuration that can
+be applied when building the IOC. Here's the difference between the two:
+
+- **RELEASE** file:
+The **RELEASE** file contains the default configuration for the motorVMC module.
+It specifies the paths to external support modules or libraries required by the
+motorVMC module. This file provides a standard configuration that is used by default
+when building the IOC.
+
+
+- **RELEASE.local** file:
+The **RELEASE.local** file is intended for local customization of the configuration.
+It allows you to override or modify the default configuration specified in the
+**RELEASE** file. By including the RELEASE.local file in the **configure/RELEASE**
+file, you can provide additional or alternative configuration settings specific to
+your local environment or requirements.
+
+</details>
+
+<details>
+<summary>what is the difference between "building inside motor" and
+"building outside motor"?</summary>
+
+
+The **RELEASE** file contains the following:
+
+```
+$ cat configure/RELEASE
+# RELEASE - Location of external support modules
+
+# Use motor/module's generated release file when buidling inside motor
+-include $(TOP)/../RELEASE.$(EPICS_HOST_ARCH).local
+# Use motorVMC's RELEASE.local when building outside motor
+-include $(TOP)/configure/RELEASE.local
+```
+
+"building inside motor" and "building outside motor" refer to different scenarios
+for compiling or building the IOC.
+
+- Building inside motor:
+When building inside motor, it implies that you are within the motor module's
+directory structure. The `$(TOP)` variable represents the top-level directory of
+the motorVMC module. In this case, the IOC is being built as part of the motor module
+itself. The line `-include $(TOP)/../RELEASE.$(EPICS_HOST_ARCH).local` is included
+in the configure/RELEASE file. This line instructs the build system to include
+the generated release file from the motor module. The release file contains
+configuration information specific to the motor module, such as paths to external
+support modules or libraries.
+
+- Building outside motor:
+When building outside motor, it means you are not within the motor module's directory
+structure. It implies that you are building the IOC separately from the motor module:
+the `make` command is issued in the ${SUPPORT_DIR}/motorVMC directory.
+In this case, the line `-include $(TOP)/configure/RELEASE.local` is included in the
+**configure/RELEASE** file. This line instructs the build system to include the
+**RELEASE.local** file from the motorVMC module. The **RELEASE.local** file contains
+paths to EPICS modules that are required to build motorVMC.
+
+</details>
+
### 4.5 Build motorVMC (Attempt #2)
If the following build succeeds, proceed to [step 4.8](4-Deploy-motorVMC.md#48-confirm-build-products-exist).
@@ -154,11 +248,15 @@ make: *** [/APSshare/epics/base-7.0.4.1/configure/RULES_DIRS:85: configure.insta
```
</details>
-Note: this build error occurs when there is a mismatch (hard mount vs soft link) between the /APSshare mount on the computer that built the support on /APSshare and the computer building the IOC. The two `MOTOR` paths actually point to the same directory.
+Note: this build error occurs when there is a mismatch (hard mount vs soft link)
+between the **/APSshare** mount on the computer that built the support on **/APSshare**
+and the computer building the IOC. The two `MOTOR` paths actually point to the same
+directory.
### 4.6 Resolve build error #2
-The **configure/CONFIG_SITE** is where the checkRelease behavior is defined. The `CHECK_RELEASE` variable can be overridden to ignore this error.
+The **configure/CONFIG_SITE** is where the checkRelease behavior is defined.
+The `CHECK_RELEASE` variable can be overridden to ignore this error.
<details>
<summary>hint</summary>
@@ -191,6 +289,36 @@ $ echo "CHECK_RELEASE = NO" > configure/CONFIG_SITE.local
```
</details>
+<details>
+<summary>what does this mean</summary>
+
+The error message indicates a conflict between the `MOTOR` definition in the
+**RELEASE.local** file and the `SUPPORT` support directory because of the
+mounting configuration or symbolic links between different machines.
+
+To resolve this error, you can modify the `CHECK_RELEASE` setting to either `NO`
+or `WARN` in the **configure/CONFIG_SITE** file. This will disable or allow the build
+to continue despite the inconsistency detected. However, please note that it's
+important to ensure the paths in the **RELEASE** files accurately reflect the correct
+locations of the support applications to avoid potential issues during runtime.
+
+Just like the **RELEASE.local** file, the **CONFIG_SITE.local** file allows for local
+customization of the build configuration. The lines
+`-include $(TOP)/../CONFIG_SITE.local` and `-include $(TOP)/configure/CONFIG_SITE.local`
+ in the **configure/CONFIG_SITE** file instruct the build system to include the
+ **CONFIG_SITE.local** files if they exist in the specified locations. The `$(TOP)`
+ variable represents the top-level directory of motorVMC.
+
+
+ Note: the linux command `$ echo "CHECK_RELEASE = NO" > configure/CONFIG_SITE.local`
+ writes the text "CHECK_RELEASE = NO" to the **configure/CONFIG_SITE.local** file.
+ If the file does not exist, the `>` sign creates the file and writes the output to it.
+ If the file already exists, the `>` sign overwrites its contents with the new output
+ (bash) or returns an error because the file already exists (tcsh).
+
+</details>
+
+
### 4.7 Build motorVMC
```
@@ -255,6 +383,8 @@ make[1]: Leaving directory '/home/beams/USERNAME/PET-S2/epics/synApps_6_2_1/supp
```
</details>
+Note: issuing a `make` in the **epics/synApps_6_2_1/support/motorVMC** directory builds the motorVMC support module, whereas running make in the **epics/synApps_6_2_1/ioc/xxx** directory builds the specific IOC application (binary), which relies on various support modules, including motorVMC. The former focuses on building the support module itself (dbd and lib), while the latter focuses on building the IOC application that utilizes the support modules (binary).
+
### 4.8 Confirm build products exist
When the build is successful there should be a database definitions file (.dbd) in the top level dbd dir, as well as a static library (.a) and a dynamic library (.so) in the arch-specific lib dir.
@@ -277,4 +407,6 @@ total 92
```
</details>
+
+
## [5 Add virtual motors to the IOC](5-Add-virtual-motors.md)
diff --git a/5-Add-virtual-motors.md b/5-Add-virtual-motors.md
index 8c21589148b8a9dde41aebb42e27805aef372420..a1b001e2bccabe81caaeaa1532d7702709bb7bb7 100644
--- a/5-Add-virtual-motors.md
+++ b/5-Add-virtual-motors.md
@@ -42,6 +42,13 @@ index e7aba0e..39736e4 100644
```
</details>
+
+<details>
+<summary>what does this mean?</summary>
+
+This step tells the build system **where** to find the **motorVMC** module, but it does not tell the build system **what** to include in the IOC build. This is determined by the **xxxApp/src/Makefile**.
+</details>
+
### 5.2 Add motorVMC to the IOC's src/Makefile
Add the motorVMC database and library to **xxxApp/src/Makefile**
@@ -101,6 +108,30 @@ index 9692f5a..14855f8 100644
```
</details>
+
+<details>
+<summary>what does that mean?</summary>
+
+```
+ifdef MOTOR_VMC
+ $(DBD_NAME)_DBD += vmcSupport.dbd
+ $(PROD_NAME)_LIBS := vmc $($(PROD_NAME)_LIBS)
+endif
+```
+
+ - `ifdef MOTOR_VMC`: This conditional statement checks if the variable `MOTOR_VMC` is defined. If `MOTOR_VMC` is defined, the code block within the `ifdef` statement is executed.
+ - `$(DBD_NAME)_DBD += vmcSupport.dbd`:
+ - This expression appends `vmcSupport.dbd` to the end of the `$(DBD_NAME)_DBD` variable. It adds the value `vmcSupport.dbd` as a new entry at the end of the list stored in `$(DBD_NAME)_DBD`.
+ - `$(DBD_NAME)_DBD` is a variable storing the names of DBD files to be included in the build
+ - `$(PROD_NAME)_LIBS := vmc $($(PROD_NAME)_LIBS)`:
+ - This expression assigns the value `vmc` as the first element in the `$(PROD_NAME)_LIBS` variable, and it appends the existing value of `$(PROD_NAME)_LIBS` after `vmc`.
+ - `$(PROD_NAME)_LIBS` is a variable that holds the names of libraries the IOC application depends on.
+ - Note: the convention is to omit the `lib` prefix and the `.a` extension (this is requirement from the **gcc** `-l` [flag](https://stackoverflow.com/questions/6231206/lib-prefix-on-libraries)).
+
+</details>
+
+
+
### 5.3 Rebuild the IOC (Attempt #1)
If the following build succeeds, proceed to [step 5.6](5-Add-virtual-motors.md#56-confirm-the-libvmc-is-included-in-the-iocs-binary).
@@ -211,6 +242,19 @@ make[1]: Leaving directory '/home/beams/USERNAME/PET-S2/epics/synApps_6_2_1/ioc/
```
$ ldd bin/${EPICS_HOST_ARCH}/xxx | grep vmc
```
+<details>
+<summary>what does this mean?</summary>
+
+The command `ldd bin/${EPICS_HOST_ARCH}/xxx | grep vmc` is used to determine if the **xxx** binary executable file in the **bin/${EPICS_HOST_ARCH}** directory has a dynamic dependency on any shared libraries containing the string "vmc" in their names. Here's what the command does:
+
+- `ldd` lists the dynamic dependencies of a binary executable file. It shows the shared libraries that the executable requires to run successfully.
+- `bin/${EPICS_HOST_ARCH}/xxx` specifies the path to the **xxx** binary executable file.
+- `| grep vmc`:
+ - the `|` symbol is a pipe operator that redirects the output of the `ldd` command to the next command in the pipeline.
+ - `grep vmc` is a command that searches for the string "vmc" in the output of the previous command (`ldd` in this case). It filters the output and displays only the lines that contain the string "vmc".
+
+</details>
+
<details>
<summary>output</summary>