This repo contains instructions for [Session 2 of the Practical Beamline Controls Training](https://wiki-ext.aps.anl.gov/blc/index.php?title=Practical_Beamline_Controls_Training#IOC_Deployment_.26_Troubleshooting).
This repo contains instructions for [Session 2 of the Practical Beamline Controls Training](https://wiki-ext.aps.anl.gov/blc/index.php?title=Practical_Beamline_Controls_Training#IOC_Deployment_.26_Troubleshooting).
## Assumptions
## Warnings
* The instructions assume the user is logged into an APS-maintained Red Hat Enterprise Linux (RHEL) computer.
This training was designed to be completed using an APS-maintained Red Hat Enterprise Linux (RHEL) computer.
* The APS-maintained Red Hat Enterprise Linux (RHEL) computer has access to /APSshare
* The instructions and solution branch assume that synApps was deployed on a path beginning with /APSshare, which is incorrect for non-APS computers.
* There will be additional errors when the IOC runs due to missing synApps modules. The instructions do not address these errors.
* It is assumed that the non-APS computer already has the [necessary prerequisites for building EPICS base](https://epics.anl.gov/base/R7-0/7-docs/README.html#software-requirements).
## Outline
## Outline
...
@@ -62,86 +65,12 @@ The use of `~` is highly discouraged; only absolute paths should be used in RELE
...
@@ -62,86 +65,12 @@ The use of `~` is highly discouraged; only absolute paths should be used in RELE
## The solution branch
## The solution branch
Both the xxx and motorVMC repos have a **solution** branch with tags for each step that:
The use of the solution branch is not recommended for non-APS computers.
When an APS computer is used, both the xxx and motorVMC repos have a **solution** branch with tags for each step that:
* allows you to run all the commands in this training **without editing a file in a text editor**.
* allows you to run all the commands in this training **without editing a file in a text editor**.
* enables jumping to a specific section
* enables jumping to a specific section
Note: the motorVMC module is only modified in section 4, so the only tags it has for later sections are 5.1 and 6.1.
Note: the motorVMC module is only modified in section 4, so the only tags it has for later sections are 5.1 and 6.1.
### How to avoid manually editing files
**Example**: You've been following the instructions in the training until [step 5.7.2](https://git.aps.anl.gov/practical_beamline_controls_training/session_2/instructions/-/blob/main/5-Add-virtual-motors.md#572-modify-iocshvmccmd), which asks to you make a lot of change to **vmc.cmd**, but you'd rather not make those changes yourself.
Do the following to see if there are any files you've modified/created manually:
```
$ git status
```
If git reports any "Changes not staged for commit" or "Untracked files", do the following to save your work to a **working** branch:
```
$ git stash
$ git checkout -b working
$ git stash apply
$ git add ${IOC_DIR}/xxx
$ git commit -m "Backup of my work before switching to a tag on the solution branch"
```
At this point you can safely proceed to step 5.7.3
```
$ git checkout 5.7.3
```
<details>
<summary>output</summary>
```
Note: switching to '5.7.3'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:
git switch -c <new-branch-name>
Or undo this operation with:
git switch -
Turn off this advice by setting config variable advice.detachedHead to false
HEAD is now at 8a0470c Modified iocsh/vmc.cmd
```
</details>
Git can also show you the changes that were made:
```
$ git show 5.7.3
```
Note: `git show <step_number>` is only useful if the previous step involved creating or modifying a file.
### How to jump to a specific section
**Example**: You already know how to deploy IOCs and EPICS modules. You'd really like to skip to section 6 to learn more about asyn troubleshooting.
Do the following:
* Follow the [quickstart instructions](README.md#quickstart).
* Complete [step 2.1](2-IOC-deployment.md#21-clone-xxx) to clone xxx.
* Complete [step 2.2](2-IOC-deployment.md#22-confirm-the-directories-exist) to cd into the IOC's directory
* Complete [step 2.3](2-IOC-deployment.md#23-choose-a-new-ioc-prefix) override the default prefix
* Complete [step 4.1](4-Deploy-motorVMC.md#41-clone-motorvmc) to clone motorVMC
* Complete [step 4.2](4-Deploy-motorVMC.md#42-confirm-directories-exist) to cd into the motorVMC directory
* Run `git checkout 6.1` to update motorVMC for step 6.1.
* Run `make` to build motorVMC. The build should succeed.
* Run `cd ${IOC_DIR}/xxx` to go back to the IOC's directory.
* Run `git checkout 6.1` to update the IOC for step 6.1.
* Run `make` to build the IOC. The build should succeed.
* Complete [step 5.10.2](5-Add-virtual-motors.md#5102-start-serverypy-in-a-different-terminal-window) to start the virtual motor controller
* Proceed to [step 6.1](6-asyn-troubleshooting.md#61-start-the-ioc)
Note: You won't have a motor screen open because you skipped [step 3.4](3-Add-simulated-motors.md#34-launch-motor-screen) and there will be autosave errors when the IOC first runs saying **.sav** and **.savB** files are not found.
