Skip to content

Commit cbad047

Browse files
gilesknapgilesknap
committed
completed tutorial 09
1 parent 3ca577a commit cbad047

File tree

5 files changed

+192
-3
lines changed

5 files changed

+192
-3
lines changed

‎docs/user/images/ghcr.png

90.6 KB
Loading

‎docs/user/images/github_actions2.png

76.1 KB
Loading

‎docs/user/images/millie.png

776 KB
Loading

‎docs/user/tutorials/07_generic_ioc.rst

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,9 @@ Much like creating a new beamline we have a template project that can be used
1818
as the starting point for a new generic IOC. Again we will create this in
1919
your personal GitHub user space.
2020

21+
Create a new ioc-XXX repo
22+
~~~~~~~~~~~~~~~~~~~~~~~~~
23+
2124
TODO: the following steps to create a new generic IOC project will be automated
2225
using an ``ec`` command.
2326

@@ -40,13 +43,37 @@ using an ``ec`` command.
4043
From the VSCode menus: File->Add Folder to Workspace
4144
then select the folder ioc-adurl
4245

43-
#. Push the new repo back to a the new repo on github
46+
#. Push the repo back to a the new repo on github
4447

4548
.. code-block:: bash
4649
4750
git remote rm origin
4851
git remote add origin [email protected]:<YOUR USER NAME>/ioc-adurl.git
49-
git push origin main
52+
git push --set-upstream origin main
53+
54+
Prepare the New Repo for Development
55+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
56+
57+
There are a few things that all new ioc-XXX repos need to do:
58+
59+
:Choose Architecture:
60+
61+
Update the file ``.github/workflows/build.yml`` to choose the architectures
62+
you are targeting find the ``architecture:`` line and change it accordingly.
63+
For this project we want ``linux`` only.
64+
65+
:Fix the tests:
66+
67+
ioc-template comes with some tests and they will continue to work. This is
68+
because they rely a default EPICS db. Specified in ``ioc/config/ioc.db``.
69+
You should update default example files in ``ioc/config/ioc.db`` to be
70+
relevant to your IOC and change the script in ``tests`` to match.
71+
72+
For now leave the tests alone as we will be working with them in
73+
`09_test_generic_ioc`.
74+
75+
Now we will go ahead and make the specific changes to the template
76+
needed for our ioc-adurl project.
5077

5178
Configure the ibek-defs Submodule
5279
---------------------------------
@@ -302,3 +329,4 @@ directory:
302329

303330
../URLDriver.cpp:22:10: fatal error: Magick++.h: No such file or directory
304331

332+
In the next tutorial we will look at how to fix build errors like this.

‎docs/user/tutorials/09_test_generic_ioc.rst

Lines changed: 162 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,166 @@
11
Testing and Deploying a Generic IOC
22
===================================
33

4+
Continuous Integration
5+
----------------------
6+
7+
An important feature of epics-containers is CI. The ioc-template that we
8+
based ioc-adurl upon has built-in CI for GitHub (and DLS internal GitLab).
9+
10+
The first thing we will do is get the project pushed up to GitHub and
11+
verify that the CI is working.
12+
13+
Before pushing the project we must push our changes to the submodule ibek-defs,
14+
then we can push the main project to GitHub too:
15+
16+
.. code-block:: bash
17+
18+
cd ibek-defs
19+
git add .
20+
git commit -m "Added ADURL"
21+
git push
22+
cd ..
23+
git add .
24+
git commit -m "update the template to ADUrl"
25+
git push
26+
27+
If you now go up to the GitHub page for the project and click on ``Actions``
28+
and click on the latest build you should see something like this:
29+
30+
.. figure:: ../images/github_actions2.png
31+
32+
GitHub Actions for ioc-adurl
33+
34+
This build should succeed.
35+
36+
Publishing the Generic IOC Container to GHCR
37+
--------------------------------------------
38+
39+
Now give your genericIOC a version tag and push it to GitHub.
40+
.. code-block:: bash
41+
42+
git tag 23.4.1
43+
git push origin 23.4.1
44+
45+
You will see the CI rebuild the container and push it to the GitHub container
46+
registry at github.io/<YOUR GITHUB USER>/ioc-adurl:<YOUR TAG>.
47+
48+
This time the build will take 2 minutes. Last time it took 10 minutes
49+
(because we were building areaDetector and graphicsMagick). The speed up
50+
is because we keep a build cache in GitHub actions.
51+
52+
Once the build is complete, if you go to your project page on GitHub
53+
https://github.com/<YOUR GITHUB ACCOUNT>/ioc-adurl you should now see a
54+
``Packages`` tab. Click on the developer package and and you should see
55+
something like this:
56+
57+
.. figure:: ../images/ghcr.png
58+
59+
The ioc-adurl container on GHCR
60+
61+
This means that the container is now available for anyone to use with a
62+
``podman/docker pull`` command as described in the ``Installation`` tab.
63+
64+
65+
Making the Tests Relevant to our Generic IOC
66+
--------------------------------------------
67+
68+
You may notice that some tests were run as part of the CI. These generic
69+
tests are used by the ioc-template and are defined in the ``tests`` directory.
70+
We need to update them to be relevant to our new generic IOC.
71+
72+
TODO: I just noticed that the tests do not use the build cache (but also
73+
they are not required to push the built container so don't hold up
74+
development).
75+
76+
In the ``ioc/config`` folder we have some default config that is used by the
77+
generic IOC if no config is provided. We can use this for testing and need
78+
to update the tests to use it too.
79+
80+
To do this remove the file ``ioc/config/ioc.db`` and replace the contents
81+
of ``ioc/config/st.cmd`` with:
82+
83+
.. code-block::
84+
85+
cd "$(TOP)"
86+
87+
dbLoadDatabase "dbd/ioc.dbd"
88+
ioc_registerRecordDeviceDriver(pdbbase)
89+
90+
URLDriverConfig("EXAMPLE.CAM", 0, 0)
91+
92+
# NDPvaConfigure(portName, queueSize, blockingCallbacks, NDArrayPort, NDArrayAddr, pvName, maxMemory, priority, stackSize)
93+
NDPvaConfigure("EXAMPLE.PVA", 2, 0, "EXAMPLE.CAM", 0, "EXAMPLE:IMAGE", 0, 0, 0)
94+
startPVAServer
95+
96+
# instantiate Database records for Url Detector
97+
dbLoadRecords("URLDriver.template","P=EXAMPLE, R=:CAM:, PORT=EXAMPLE.CAM, TIMEOUT=1, ADDR=0")
98+
dbLoadRecords("NDPva.template", "P=EXAMPLE, R=:PVA:, PORT=EXAMPLE.PVA, ADDR=0, TIMEOUT=1, NDARRAY_PORT=EXAMPLE.CAM, NDARRAY_ADR=0, ENABLED=1")
99+
100+
# start IOC shell
101+
iocInit
102+
103+
# poke some records
104+
dbpf "EXAMPLE:CAM:AcquirePeriod", "0.1"
105+
106+
Next, remove the folders ``tests/example-config`` and ``tests/example-ibek-config``.
107+
108+
Then edit the ``tests/run_tests.sh`` file. Remove the test blocks titled
109+
``Test an ibek IOC`` and ``Test a hand coded st.cmd IOC`` leaving just the
110+
block called ``Test the default example IOC``. Finally edit the block to
111+
look like this:
112+
113+
.. code-block:: bash
114+
115+
116+
...
117+
fi
118+
podman run ${ioc_args}
119+
check_pv 'EXAMPLE:CAM:AcquirePeriod' '0.1'
120+
121+
Now try out the test with the following command:
122+
123+
.. code-block:: bash
124+
125+
./tests/run_tests.sh
126+
127+
We have made a very simple test that only checks one PV value, but that is
128+
good enough to validate that the IOC is running and that the config is
129+
being loaded. You can add more sophisticated tests as needed to your
130+
own generic IOCs.
131+
132+
If you had any issues with getting this tutorial working, you can get a
133+
fully working version of the ioc-adurl project from the following link:
134+
135+
https://github.com/epics-containers/ioc-adurl
136+
137+
Try out some GUI
138+
----------------
139+
140+
To make the example more interesting I have provided an edm screen for it.
141+
142+
After running the tests in the previous section you should have a running
143+
container still active. You can see this using ``podman ps``. You should
144+
see that ``ioc-template-test-container`` is still running. You can start it
145+
again with ``tests/run_tests.sh`` if it is not.
146+
147+
Now get the edm screens and launch them as follows.
148+
149+
.. code-block:: bash
150+
151+
cd /tmp
152+
git clone [email protected]:epics-containers/ioc-adurl.git
153+
cd ioc-adurl
154+
opi/example.sh
155+
156+
You should see the C2DataViewer. Click on auto button and you should see:
157+
158+
.. figure:: ../images/millie.png
159+
160+
Millie the Labradoodle
161+
162+
To work out how Millie got into the viewer, take a look at example.sh, I leave
163+
this as an exercise for the reader.
164+
165+
4166

5-
don't forget to remove the RTEMS build from CI.

0 commit comments

Comments
 (0)