update ioc_changes? to 3.4.0

Author: gilesknap

docs/explanations/introduction.md

@@ -39,7 +39,7 @@ forks of these repositories.
 
 #### Generic IOCs and instances
 
-An important principal of the approach presented here is that an IOC container image represents a 'Generic' IOC. The Generic IOC image is used for all IOC instances that connect to a given class of device. For example the Generic IOC image here: [ghcr.io/epics-containers/ioc-adaravis-linux-runtime:2024.2.2 ](https://github.com/epics-containers/ioc-adaravis/pkgs/container/ioc-adaravis-linux-runtime) uses the AreaDetector driver ADAravis to connect to GigE cameras.
+An important principal of the approach presented here is that an IOC container image represents a 'Generic' IOC. The Generic IOC image is used for all IOC instances that connect to a given class of device. For example the Generic IOC image here: [ghcr.io/epics-containers/ioc-adaravisruntime:2024.2.2 ](https://github.com/epics-containers/ioc-adaravis/pkgs/container/ioc-adaravisruntime) uses the AreaDetector driver ADAravis to connect to GigE cameras.
 
 An IOC instance runs in a container runtime by loading two things:
 

docs/how-to/debug.md

@@ -41,7 +41,7 @@ Are you sure ? [y/N]: y
 <font color="#5F8787">docker container create --name busybox -v bl01t-ea-test-02_config:/copyto busybox</font>
 <font color="#5F8787">docker cp /home/giles/tutorial/bl01t/services/bl01t-ea-test-02/config/ioc.yaml busybox:copyto</font>
 <font color="#5F8787">docker rm -f busybox</font>
-<font color="#5F8787">docker run -dit --net host --restart unless-stopped -l is_IOC=true -l version=2024.2.17-b8.30 -v bl01t-ea-test-02_config:/epics/ioc/config/ -e IOC_NAME=bl01t-ea-test-02  --name bl01t-ea-test-02 ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2024.2.2</font>
+<font color="#5F8787">docker run -dit --net host --restart unless-stopped -l is_IOC=true -l version=2024.2.17-b8.30 -v bl01t-ea-test-02_config:/epics/ioc/config/ -e IOC_NAME=bl01t-ea-test-02  --name bl01t-ea-test-02 ghcr.io/epics-containers/ioc-adsimdetectorruntime:2024.2.2</font>
 76c2834dac805780b3329af91c332abb90fb2692a510c11b888b82e48f60b44f
 <font color="#5F8787">docker ps -f name=bl01t-ea-test-02 --format &apos;{{.Names}}&apos;</font>
 </pre>
@@ -59,7 +59,7 @@ Now you can tell `ec` to stop the IOC instance and then run it in a way that you
 
 ```bash
 ec stop bl01t-ea-test-02
-docker run --entrypoint bash -it --net host -l is_IOC=true -l version=2024.2.17-b8.30 -v bl01t-ea-test-02_config:/epics/ioc/config/ -e IOC_NAME=bl01t-ea-test-02  --name bl01t-ea-test-02-debug ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2024.2.2
+docker run --entrypoint bash -it --net host -l is_IOC=true -l version=2024.2.17-b8.30 -v bl01t-ea-test-02_config:/epics/ioc/config/ -e IOC_NAME=bl01t-ea-test-02  --name bl01t-ea-test-02-debug ghcr.io/epics-containers/ioc-adsimdetectorruntime:2024.2.2
 ```
 
 You should now be in a shell inside the container. You can look at the files and run the IOC instance manually to see what the error is. You can re-run the IOC instance multiple times and you can even install your favourite editor or debugging tools.

docs/tutorials/create_ioc.md

@@ -69,10 +69,10 @@ You will now have vscode and open and editing the values.yaml file. Add the foll
 ```yaml
 shared:
   ioc-instance:
-    image: ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2024.4.1
+    image: ghcr.io/epics-containers/ioc-adsimdetectorruntime:2024.4.1
 ```
 
-This tells the IOC Instance to run in the `ioc-adsimdetector-linux-runtime`
+This tells the IOC Instance to run in the `ioc-adsimdetectorruntime`
 container. This container was built by the Generic IOC source repo here
 <https://github.com/epics-containers/ioc-adsimdetector>. The container has
 support for AreaDetector and ADSimDetector compiled into its IOC binary.

docs/tutorials/debug_generic_ioc.md

@@ -134,7 +134,7 @@ You should find the build succeeds. But this is not the whole story. There
 is another line in `install.h` that I added to make this work:
 
 ```bash
-ibek support add-config-macro ${NAME} PCRE_LIB /usr/lib/x86_64-linux-gnu
+ibek support add-config-macro ${NAME} PCRE_LIB /usr/lib/x86_64gnu
 ```
 
 This added a macro to `CONFIG_SITE.linux-x86_64.Common` that tells the

docs/tutorials/deploy_example.md

@@ -42,6 +42,7 @@ have valid configuration.
 For the moment just check that your CI passed and if not review that you
 have followed the instructions in the previous tutorial correctly.
 
+(setup-beamline-bl01t)=
 ## Set up Environment for BL01T Beamline
 
 The standard way to set up your environment for any ec services repository is to get the environment.sh script from the domain repository and source it.
@@ -162,7 +163,7 @@ bdbd155d437361fe88bce0faa0ddd3cd225a9026287ac5e73545aeb4ab3a67e9
 $ ec ps -w
 | name             | version  | running | restarts | deployed            | image                                                             |
 |------------------|----------|---------|----------|---------------------|-------------------------------------------------------------------|
-| bl01t-ea-test-01 | 2024.3.1 | true    | 0        | 2024-03-19 11:10:53 | ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2024.4.1 |
+| bl01t-ea-test-01 | 2024.3.1 | true    | 0        | 2024-03-19 11:10:53 | ghcr.io/epics-containers/ioc-adsimdetectorruntime:2024.4.1 |
 ```
 
 ### IMPORTANT: deploy-local vs deploy
@@ -191,7 +192,7 @@ ec ps
 Generic IOCs.
 
 You may have noticed that the IOC instance has is showing that it has
-an image `ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2024.4.1`.
+an image `ghcr.io/epics-containers/ioc-adsimdetectorruntime:2024.4.1`.
 
 This is a Generic IOC image and all IOC Instances must be based upon one
 of these images. This IOC instance has no startup script and is therefore

docs/tutorials/dev_container.md

@@ -21,6 +21,11 @@ which appear in the `iocs` folder of an {any}`ec-services-repo`. e.g.:
 - for Kubernetes: changes to the global values.yaml
   file found in `helm/shared`, these affect all IOCs in the repository.
 
+To make a change like this requires:
+
+- change the IOC instance ioc.yaml or values.yaml
+- redeploy the IOC with `ec deploy-local` or `ec deploy`
+
 (changes_2)=
 ### Changing the Generic IOC
 
@@ -34,14 +39,28 @@ Types of changes include:
    - adding new support modules
    - altering the system dependencies installed into the container image
 
+To make a change like this requires:
+
+- make changes to the Generic IOC Dockerfile
+- push the changes and tag the repo - this will release a new container image
+- change the IOC instance values.yaml to point at the new container image
+- redeploy the IOC with `ec deploy-local` or `ec deploy`
+
+
 (changes_3)=
 ### Changing the dependencies
 
-Sometimes you will need to alter the support modules used by the Generic IOC. To make use of these changes would require:
+Sometimes you will need to alter the support modules used by the Generic IOC. Reasons to do this include:
+
+- fix a bug in a support module
+- update to support a new version of the device
+- update to support a feature of the device not yet implemented in the support module
+
+To make a change like this would require:
 
-- publishing a new release of the support module,
-- updating and publishing the Generic IOC
-- updating and publishing the IOC instance
+- making the change in the support module source code
+- test and publish a release of the above
+- repeat the steps in [](changes_2)
 
 ## Need for a Developer Container
 
@@ -167,22 +186,14 @@ Once built, open the project in VSCode:
 code .
 ```
 
-When it opens, VSCode may prompt you to open in a devcontainer. If not then click
-the green icon in the bottom left of the VSCode window and select
-`Reopen in Container`.
+When it opens, VSCode may prompt you to open in a devcontainer, if so the choose to do so. If not then use `ctrl-shift-p` and type `Reopen in Container`.
 
 You should now be *inside* the container. All terminals started in VSCode will
 be running inside the container. Every file that you open with the VSCode editor
 will be inside the container.
 
-There are some caveats because some folders are mounted from the host file
-system. For example, the `ioc-adsimdetector` project folder
-is mounted into the container as a volume. It is mounted under
-`/workspaces/ioc-adsimdetector`. This means that you can edit the source code
-from your local machine and the changes will be visible inside the container and
-outside the container. This is a good thing as you should consider the container
-filesystem to be a temporary filesystem that will be destroyed when the container
-is rebuilt or deleted.
+There are some caveats because some folders are mounted from the host file system. For example, the `ioc-adsimdetector` project folder
+is mounted into the container as a volume. It is mounted under `/workspaces/ioc-adsimdetector`. This means that you can edit the source code from your local machine and the changes will be visible inside the container and outside the container. This is a good thing as you should consider the container filesystem to be a temporary filesystem, because will be destroyed when the container is rebuilt or deleted.
 
 ### Preparing the IOC for Testing
 

docs/tutorials/ioc_changes1.md

@@ -9,7 +9,7 @@ and deployed the IOC instance in a previous tutorial without one. It is up to
 you how you choose to make these types of changes. Types 2,3 do require a
 devcontainer because they involve compiling Generic IOC / support module code.
 
-These instructions are for running inside the devcontainer. If you closed your developer container from the last tutorial, then open it again now. To do open your `bl01t` folder in vscode and then press `Ctrl-Shift-P` and type `Remote-Containers: Reopen in Container`.
+These instructions are for running inside the devcontainer. If you closed your developer container from the last tutorial, then open it again now. To do so, open your `ioc-adsimdetector` folder in vscode and then press `Ctrl-Shift-P` and type `Remote-Containers: Reopen in Container`.
 
 We are going to add a hand crafted EPICS DB file to the IOC instance. This will be a simple record that we will be able to query to verify that the change is working. We will use the version of the IOC instance that used `ioc.yaml`. If you changed to using raw startup assets in the previous tutorial then revert to using `ioc.yaml` for this tutorial or see [](raw-startup-assets).
 
@@ -74,10 +74,7 @@ You can change this and make your devcontainer network isolated by removing the
 host. You may want to isolate your development network if multiple developers are working on the same subnet. In this case some other solution is required for running OPI tools on the host (TODO add link to solution - likely to be container networks).
 :::
 
-Because of the symlink between `/epics/ioc/config` and
-`/workspaces/bl01t/services/bl01t-ea-test-02/config` the same files you are testing
-by launching the IOC inside of the devcontainer are also ready to be
-committed and pushed to the bl01t repo. i.e.:
+Because of the symlink between `/epics/ioc/config` and `/workspaces/bl01t/services/bl01t-ea-test-02/config` the same files you are testing by launching the IOC inside of the devcontainer are also ready to be committed and pushed to the bl01t repo. The following commands show how to do this:
 
 ```bash
 # Do this from a host terminal (not a devcontainer terminal)
@@ -92,6 +89,8 @@ git push origin 2024.3.2
 ec deploy bl01t-ea-test-02 2024.3.2
 ```
 
+NOTE: the above assumes you have an active python virtual environment with the `edge-containers-cli` installed and you have sourced the beamline environment file (for a reminder of how to do this see {any}`setup-beamline-bl01t`).
+
 You can now see that the versioned IOC instance is running and loading the extra.db by looking at its log with:
 
 ```bash

docs/tutorials/rtems_ioc.md

@@ -125,8 +125,8 @@ in the cluster. The matrix of targets also includes an architecture dimension,
 at present the ioc-template supports two architectures, `linux` and
 `rtems`, thus there are 4 targets in total as follows:
 
-- ghcr.io/epics-containers/ioc-template-linux-runtime
-- ghcr.io/epics-containers/ioc-template-linux-developer
+- ghcr.io/epics-containers/ioc-templateruntime
+- ghcr.io/epics-containers/ioc-templatedeveloper
 - ghcr.io/epics-containers/ioc-template-rtems-runtime
 - ghcr.io/epics-containers/ioc-template-rtems-developer