Skip to content

Commit a2e5303

Browse files
gilesknapgilesknap
authored
Merge pull request #82 from epics-containers/remove-dev
remove references to the dev namespace of ke command
2 parents a1994b1 + d24fc43 commit a2e5303

File tree

4 files changed

+45
-103
lines changed

4 files changed

+45
-103
lines changed

‎docs/user/reference/cli.rst

Lines changed: 1 addition & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,7 @@ The python project ``epics-containers-cli`` is installed as part of the
77
Python section of the initial tutorial `../tutorials/setup_workstation`.
88
It provides a command line function ``ec`` with support for:
99

10-
- building and debugging Generic IOC Containers
11-
- deploying, managing and debugging IOC Instances
10+
- deploying, managing and debugging IOCs and other application Instances
1211

1312
The CLI is just a thin wrapper around the underlying tools that do the real
1413
work:
@@ -23,43 +22,6 @@ when working on multiple beamlines. This is because it uses the environment
2322
setup by the beamline repo's ``environment.sh`` script. See `environment`.
2423

2524
To see the available commands, run ``ec --help``.
26-
Much of the functionality is available through subcommands dev and ioc. To get
27-
full details of a given command type the full command plus ``--help``. For
28-
example:
29-
30-
.. raw:: html
31-
32-
<pre>$ ec dev launch --help
33-
<b> </b>
34-
<b> </b><font color="#A2734C"><b>Usage: </b></font><b>ec dev launch [OPTIONS] IOC_INSTANCE </b>
35-
<b> </b>
36-
Launch an IOC instance using configuration from a domain repo. Or by passing a
37-
generic IOC image ID. Can be used for local testing of IOC instances. You may
38-
find the devcontainer a more convenient way to do this.
39-
40-
<font color="#AAAAAA">╭─ Arguments ───────────────────────────────────────────────────────────────────╮</font>
41-
<font color="#AAAAAA">│ </font><font color="#C01C28">*</font> ioc_instance <font color="#A2734C"><b>DIRECTORY</b></font> local IOC definition folder from domain │
42-
<font color="#AAAAAA">│ repo │</font>
43-
<font color="#AAAAAA">│ [default: None] │</font>
44-
<font color="#AAAAAA">│ </font><font color="#80121A">[required] </font> │
45-
<font color="#AAAAAA">╰───────────────────────────────────────────────────────────────────────────────╯</font>
46-
<font color="#AAAAAA">╭─ Options ─────────────────────────────────────────────────────────────────────╮</font>
47-
<font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--execute</b></font> <font color="#A2734C"><b>TEXT </b></font> command to execute in the container. │
48-
<font color="#AAAAAA">│ Defaults to executing the IOC │</font>
49-
<font color="#AAAAAA">│ [default: /epics/ioc/start.sh; bash] │</font>
50-
<font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--target</b></font> <font color="#6C4C32"><b>[developer|runtime]</b></font> choose runtime or developer target │
51-
<font color="#AAAAAA">│ [default: developer] │</font>
52-
<font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--image</b></font> <font color="#A2734C"><b>TEXT </b></font> override container image to use │
53-
<font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--tag</b></font> <font color="#A2734C"><b>TEXT </b></font> override image tag to use. │
54-
<font color="#AAAAAA">│ [default: None] │</font>
55-
<font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--args</b></font> <font color="#A2734C"><b>TEXT </b></font> Additional args for podman/docker, │
56-
<font color="#AAAAAA">│ &apos;must be quoted&apos; │</font>
57-
<font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--ioc-name</b></font> <font color="#A2734C"><b>TEXT </b></font> container name override. Use to run │
58-
<font color="#AAAAAA">│ multiple instances │</font>
59-
<font color="#AAAAAA">│ [default: test-ioc] │</font>
60-
<font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--help</b></font> <font color="#A2734C"><b> </b></font> Show this message and exit. │
61-
<font color="#AAAAAA">╰───────────────────────────────────────────────────────────────────────────────╯</font>
62-
</pre>
6325

6426
It may be instructive to understand the underlying tools and how they are
6527
are being called. For this reason ``ec`` supports a ``-v`` option to show

‎docs/user/tutorials/debug_generic_ioc.rst

Lines changed: 15 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ the devcontainer (make sure you have ``ec`` installed):
4242
.. code-block:: bash
4343
4444
cd ioc-lakeshore340 # where you cloned it
45-
ec dev build
45+
./build
4646
4747
First of all, notice the build cache. The build rapidly skips
4848
over all the steps until it gets to the StreamDevice support module. The,
@@ -66,9 +66,17 @@ where the last successful Dockerfile command was run. This means that we can
6666
investigate the build failure by running a shell in the container. ``ec``
6767
provides us with the following convenience command to do this:
6868

69-
.. code-block:: bash
7069

71-
ec dev debug-last
70+
- scroll up the page until you see the last successful build step e.g.
71+
72+
.. code-block:: bash
73+
STEP 14/19: COPY ibek-support/StreamDevice/ StreamDevice/
74+
--> 631291db1751
75+
STEP 15/19: RUN StreamDevice/install.sh 2.8.24
76+
... etc ...
77+
78+
- copy the hash of the step you want to debug e.g. ``631291db1751`` in this case
79+
- podman run -it --entrypoint /bin/bash 631291db1751 # (the hash you copied)
7280

7381
Now we have a prompt inside the part-built container and can retry the failed
7482
command.
@@ -150,26 +158,9 @@ adding to the install.sh or Dockerfile, then try a full rebuild.
150158
Making Changes Inside the Container
151159
-----------------------------------
152160

153-
You will find that the container includes busybox tools, vim and ifconfig.
154-
These should provide enough tools to investigate and fix most build problems.
155-
You are also
156-
free to use apt-get to install any other tools you need as demonstrated above.
157-
(type busybox to see the list of available tools).
158-
159-
160-
Other ``ec dev`` Commands
161-
-------------------------
162-
163-
The ``ec dev`` namespace provides a number of other commands for working outside
164-
of developer containers. These were primarily developed before the use
165-
of developer containers matured. If you prefer not to use developer containers
166-
for any reason then take a look at the help as follows:
167-
168-
.. code-block:: bash
169-
170-
ec dev --help
161+
You will find that the container includes busybox tools, vim and ifconfig. These
162+
should provide enough tools to investigate and fix most build problems. You are
163+
also free to use apt-get to install any other tools you need as demonstrated
164+
above. (type busybox to see the list of available tools).
171165

172-
You should be able to perform most of the same tasks that the tutorials teach.
173166

174-
Don't forget that you can always use ``ec -v dev ...`` to get output showing
175-
the underlying docker/podman and git commands ``ec`` is using.

‎docs/user/tutorials/dev_container.rst

Lines changed: 27 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -82,9 +82,14 @@ The next section will show you how to use this feature. Note that you can use
8282
any IDE that supports remote development in a container, you could also
8383
simply launch the developer container in a shell and use it via CLI only.
8484

85-
TODO: add features to ``ec dev`` to launch the container in developer mode,
86-
with appropriate host mounts. This will enable non vscode users developer
87-
containers.
85+
If you want to use the CLI and terminal based editors like ``neovim`` then
86+
you should use the developer container CLI to get your developer container
87+
started. This means the configuration in ``.devcontainer/devcontainer.json``
88+
is used to start the container. This is necessary as that is where the
89+
useful host filesystem mounts and other config items are defined. See
90+
`devcontainer-cli<https://code.visualstudio.com/docs/devcontainers/devcontainer-cli>`_
91+
for details.
92+
8893

8994
Starting a Developer Container
9095
------------------------------
@@ -95,10 +100,10 @@ Starting a Developer Container
95100

96101
There is a
97102
`bug in VSCode devcontainers extension <https://github.com/microsoft/vscode-remote-release/issues/8557>`_
98-
at the time of writing
99-
that makes it incompatible with podman and an SELinux enabled /tmp directory.
100-
This will affect most Redhat users and you will see an error regarding
101-
permissions on the /tmp folder when VSCode is building your devcontainer.
103+
at the time of writing that makes it incompatible with podman and an SELinux
104+
enabled /tmp directory. This will affect most Redhat users and you will see an
105+
error regarding permissions on the /tmp folder when VSCode is building your
106+
devcontainer.
102107

103108
Here is a workaround that disables SELinux labels in podman.
104109
Paste this into a terminal:
@@ -110,37 +115,29 @@ Starting a Developer Container
110115
Preparation
111116
~~~~~~~~~~~
112117

113-
For this section we will work with the ADSimDetector Generic IOC that we
114-
used in previous tutorials. Let's go and fetch a version of the Generic IOC
115-
source and build it locally.
118+
For this section we will work with the ADSimDetector Generic IOC that we used in
119+
previous tutorials. Let's go and fetch a version of the Generic IOC source and
120+
build it locally.
116121

117122
For the purposes of this tutorial we will place the source in a folder right
118123
next to your test beamline ``bl01t``:
119124

120125
.. code-block:: bash
121126
122-
# starting from folder bl01t so that the clone is next to bl01t
123-
cd ..
124-
git clone --recursive [email protected]:epics-containers/ioc-adsimdetector.git
125-
cd ioc-adsimdetector
126-
ec dev build
127-
128-
The last step uses one of the ``ec dev`` sub commands to build the developer
129-
target of the container to your local container cache. This will take a few
130-
minutes to complete. A philosophy of epics-containers is that Generic IOCs
131-
build all of their own support. This is to avoid problematic dependency trees.
132-
For this reason building something as complex as AreaDetector will take a
133-
few minutes when you first build it.
134-
135-
A nice thing about containers is that the build is
136-
cached so that a second build will be almost instant unless you have changed
137-
something that requires some steps to be rebuilt.
127+
# starting from folder bl01t so that the clone is next to bl01t
128+
cd ..
129+
git clone [email protected]:epics-containers/ioc-adsimdetector.git
130+
cd ioc-adsimdetector
131+
./build
138132
139-
The ``ec dev`` commands are a set of convenience commands
140-
for working on Generic IOCs from *outside* of the container. These commands
141-
are useful for debugging container builds: although most work is done inside
142-
the container, you will need these commands if it fails to build.
133+
This will take a few minutes to complete. A philosophy of epics-containers is
134+
that Generic IOCs build all of their own support. This is to avoid problematic
135+
dependency trees. For this reason building something as complex as AreaDetector
136+
will take a few minutes when you first build it.
143137

138+
A nice thing about containers is that the build is cached so that a second build
139+
will be almost instant unless you have changed something that requires some
140+
steps to be rebuilt.
144141

145142
.. note::
146143

‎docs/user/tutorials/ioc_changes2.rst

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -63,16 +63,8 @@ The ``build`` script does two things.
6363
between all the EPICS IOC container images and contains the support YAML files
6464
that tell ``ibek`` how to build support modules inside the container
6565
environment and how to use them at runtime.
66-
- it builds the Generic IOC container image locally.
67-
68-
.. note::
69-
70-
The ``build`` script is a convenience script that is provided in the
71-
Generic IOC Template project. It is exactly equivalent to cloning
72-
with ``--recursive`` flag and then running ``ec dev build``. Equally,
73-
opening a vscode dev container will also build the container for you, but it
74-
does require the ``ibek-support`` submodule to be present - using
75-
``--recursive`` flag to git clone ensures this.
66+
- it builds the Generic IOC container image developer target locally using
67+
podman or docker.
7668

7769
Verify the Example IOC Instance is working
7870
------------------------------------------

0 commit comments

Comments
 (0)