diff --git a/README.md b/README.md index 95800479b3dfee574b77dd7ff237e244f017d79d..e710c3efc76e751be8bab408b8d27aac9adc0fcd 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,13 @@ 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. -* The APS-maintained Red Hat Enterprise Linux (RHEL) computer has access to /APSshare +This training was designed to be completed using an APS-maintained Red Hat Enterprise Linux (RHEL) computer. + +* 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 @@ -62,86 +65,12 @@ The use of `~` is highly discouraged; only absolute paths should be used in RELE ## 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**. * 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. -### 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.