remove references to the dev namespace of ke command

epics-containers · Jan 29, 2024 · 1a3e19a · 1a3e19a
1 parent a1994b1
commit 1a3e19a
Show file tree

Hide file tree

Showing 4 changed files with 46 additions and 103 deletions.
diff --git a/docs/user/reference/cli.rst b/docs/user/reference/cli.rst
@@ -7,8 +7,7 @@ The python project ``epics-containers-cli`` is installed as part of the
 Python section of the initial tutorial `../tutorials/setup_workstation`.
 It provides a command line function ``ec`` with support for:
 
-- building and debugging Generic IOC Containers
-- deploying, managing and debugging IOC Instances
+- deploying, managing and debugging IOCs and other application Instances
 
 The CLI is just a thin wrapper around the underlying tools that do the real
 work:
@@ -23,43 +22,6 @@ when working on multiple beamlines. This is because it uses the environment
 setup by the beamline repo's ``environment.sh`` script. See `environment`.
 
 To see the available commands, run ``ec --help``.
-Much of the functionality is available through subcommands dev and ioc. To get
-full details of a given command type the full command plus ``--help``. For
-example:
-
-.. raw:: html
-
-    <pre>$ ec dev launch --help
-    <b>                                                                                 </b>
-    <b> </b><font color="#A2734C"><b>Usage: </b></font><b>ec dev launch [OPTIONS] IOC_INSTANCE                                     </b>
-    <b>                                                                                 </b>
-    Launch an IOC instance using configuration from a domain repo. Or by passing a
-    generic IOC image ID. Can be used for local testing of IOC instances. You may
-    find the devcontainer a more convenient way to do this.
-
-    <font color="#AAAAAA">╭─ Arguments ───────────────────────────────────────────────────────────────────╮</font>
-    <font color="#AAAAAA">│ </font><font color="#C01C28">*</font>    ioc_instance      <font color="#A2734C"><b>DIRECTORY</b></font>  local IOC definition folder from domain     │
-    <font color="#AAAAAA">│                                   repo                                        │</font>
-    <font color="#AAAAAA">│                                   [default: None]                             │</font>
-    <font color="#AAAAAA">│                                   </font><font color="#80121A">[required]                                 </font> │
-    <font color="#AAAAAA">╰───────────────────────────────────────────────────────────────────────────────╯</font>
-    <font color="#AAAAAA">╭─ Options ─────────────────────────────────────────────────────────────────────╮</font>
-    <font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--execute</b></font>         <font color="#A2734C"><b>TEXT               </b></font>  command to execute in the container.   │
-    <font color="#AAAAAA">│                                        Defaults to executing the IOC          │</font>
-    <font color="#AAAAAA">│                                        [default: /epics/ioc/start.sh; bash]   │</font>
-    <font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--target</b></font>          <font color="#6C4C32"><b>[developer|runtime]</b></font>  choose runtime or developer target     │
-    <font color="#AAAAAA">│                                        [default: developer]                   │</font>
-    <font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--image</b></font>           <font color="#A2734C"><b>TEXT               </b></font>  override container image to use        │
-    <font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--tag</b></font>             <font color="#A2734C"><b>TEXT               </b></font>  override image tag to use.             │
-    <font color="#AAAAAA">│                                        [default: None]                        │</font>
-    <font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--args</b></font>            <font color="#A2734C"><b>TEXT               </b></font>  Additional args for podman/docker,     │
-    <font color="#AAAAAA">│                                        &apos;must be quoted&apos;                       │</font>
-    <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    │
-    <font color="#AAAAAA">│                                        multiple instances                     │</font>
-    <font color="#AAAAAA">│                                        [default: test-ioc]                    │</font>
-    <font color="#AAAAAA">│ </font><font color="#2AA1B3"><b>--help</b></font>            <font color="#A2734C"><b>                   </b></font>  Show this message and exit.            │
-    <font color="#AAAAAA">╰───────────────────────────────────────────────────────────────────────────────╯</font>
-    </pre>
 
 It may be instructive to understand the underlying tools and how they are
 are being called. For this reason ``ec`` supports a ``-v`` option to show

diff --git a/docs/user/tutorials/debug_generic_ioc.rst b/docs/user/tutorials/debug_generic_ioc.rst
@@ -42,7 +42,7 @@ the devcontainer (make sure you have ``ec`` installed):
 .. code-block:: bash
 
     cd ioc-lakeshore340 # where you cloned it
-    ec dev build
+    ./build
 
 First of all, notice the build cache. The build rapidly skips
 over all the steps until it gets to the StreamDevice support module. The,
@@ -66,9 +66,18 @@ where the last successful Dockerfile command was run. This means that we can
 investigate the build failure by running a shell in the container. ``ec``
 provides us with the following convenience command to do this:
 
+
+- scroll up the page until you see the last successful build step e.g.
+
 .. code-block:: bash
 
-    ec dev debug-last
+    STEP 14/19: COPY ibek-support/StreamDevice/ StreamDevice/
+    --> 631291db1751
+    STEP 15/19: RUN StreamDevice/install.sh 2.8.24
+    ... etc ...
+
+- copy the hash of the step you want to debug e.g. ``631291db1751`` in this case
+- podman run -it --entrypoint /bin/bash 631291db1751 # (the hash you copied)
 
 Now we have a prompt inside the part-built container and can retry the failed
 command.
@@ -150,26 +159,9 @@ adding to the install.sh or Dockerfile, then try a full rebuild.
 Making Changes Inside the Container
 -----------------------------------
 
-You will find that the container includes busybox tools, vim and ifconfig.
-These should provide enough tools to investigate and fix most build problems.
-You are also
-free to use apt-get to install any other tools you need as demonstrated above.
-(type busybox to see the list of available tools).
-
-
-Other ``ec dev`` Commands
--------------------------
-
-The ``ec dev`` namespace provides a number of other commands for working outside
-of developer containers. These were primarily developed before the use
-of developer containers matured. If you prefer not to use developer containers
-for any reason then take a look at the help as follows:
-
-.. code-block:: bash
-
-    ec dev --help
+You will find that the container includes busybox tools, vim and ifconfig. These
+should provide enough tools to investigate and fix most build problems. You are
+also free to use apt-get to install any other tools you need as demonstrated
+above. (type busybox to see the list of available tools).
 
-You should be able to perform most of the same tasks that the tutorials teach.
 
-Don't forget that you can always use ``ec -v dev ...`` to get output showing
-the underlying docker/podman and git commands ``ec`` is using.
diff --git a/docs/user/tutorials/dev_container.rst b/docs/user/tutorials/dev_container.rst
@@ -65,7 +65,7 @@ dependencies on our local machine. Instead we can use a developer container,
 and in fact our Generic IOC *is* our developer container.
 
 When the CI builds a Generic IOC it creates
-`two targets <https://github.com/orgs/epics-containers/packages?repo_name=ioc-adsimdetector>`_:
+`two targets <https://github.com/orgs/epics-containers/packages?repo_name=ioc-adsimdetector>`_
 
 :developer: this target installs all the build tools and build time dependencies
    into the container image. It then compiles the support modules and IOC.
@@ -82,9 +82,14 @@ The next section will show you how to use this feature. Note that you can use
 any IDE that supports remote development in a container, you could also
 simply launch the developer container in a shell and use it via CLI only.
 
-TODO: add features to ``ec dev`` to launch the container in developer mode,
-with appropriate host mounts. This will enable non vscode users developer
-containers.
+If you want to use the CLI and terminal based editors like ``neovim`` then
+you should use the developer container CLI to get your developer container
+started. This means the configuration in ``.devcontainer/devcontainer.json``
+is used to start the container. This is necessary as that is where the
+useful host filesystem mounts and other config items are defined. See
+`devcontainer-cli <https://code.visualstudio.com/docs/devcontainers/devcontainer-cli>`_
+for details.
+
 
 Starting a Developer Container
 ------------------------------
@@ -95,10 +100,10 @@ Starting a Developer Container
 
   There is a
   `bug in VSCode devcontainers extension <https://github.com/microsoft/vscode-remote-release/issues/8557>`_
-  at the time of writing
-  that makes it incompatible with podman and an SELinux enabled /tmp directory.
-  This will affect most Redhat users and you will see an error regarding
-  permissions on the /tmp folder when VSCode is building your devcontainer.
+  at the time of writing that makes it incompatible with podman and an SELinux
+  enabled /tmp directory. This will affect most Redhat users and you will see an
+  error regarding permissions on the /tmp folder when VSCode is building your
+  devcontainer.
 
   Here is a workaround that disables SELinux labels in podman.
   Paste this into a terminal:
@@ -110,37 +115,29 @@ Starting a Developer Container
 Preparation
 ~~~~~~~~~~~
 
-For this section we will work with the ADSimDetector Generic IOC that we
-used in previous tutorials. Let's go and fetch a version of the Generic IOC
-source and build it locally.
+For this section we will work with the ADSimDetector Generic IOC that we used in
+previous tutorials. Let's go and fetch a version of the Generic IOC source and
+build it locally.
 
 For the purposes of this tutorial we will place the source in a folder right
 next to your test beamline ``bl01t``:
 
 .. code-block:: bash
 
-    # starting from folder bl01t so that the clone is next to bl01t
-    cd ..
-    git clone --recursive [email protected]:epics-containers/ioc-adsimdetector.git
-    cd ioc-adsimdetector
-    ec dev build
-
-The last step uses one of the ``ec dev`` sub commands to build the developer
-target of the container to your local container cache. This will take a few
-minutes to complete. A philosophy of epics-containers is that Generic IOCs
-build all of their own support. This is to avoid problematic dependency trees.
-For this reason building something as complex as AreaDetector will take a
-few minutes when you first build it.
-
-A nice thing about containers is that the build is
-cached so that a second build will be almost instant unless you have changed
-something that requires some steps to be rebuilt.
+  # starting from folder bl01t so that the clone is next to bl01t
+  cd ..
+  git clone [email protected]:epics-containers/ioc-adsimdetector.git
+  cd ioc-adsimdetector
+  ./build
 
-The ``ec dev`` commands are a set of convenience commands
-for working on Generic IOCs from *outside* of the container. These commands
-are useful for debugging container builds: although most work is done inside
-the container, you will need these commands if it fails to build.
+This will take a few minutes to complete. A philosophy of epics-containers is
+that Generic IOCs build all of their own support. This is to avoid problematic
+dependency trees. For this reason building something as complex as AreaDetector
+will take a few minutes when you first build it.
 
+A nice thing about containers is that the build is cached so that a second build
+will be almost instant unless you have changed something that requires some
+steps to be rebuilt.
 
 .. note::
 

diff --git a/docs/user/tutorials/ioc_changes2.rst b/docs/user/tutorials/ioc_changes2.rst
@@ -63,16 +63,8 @@ The ``build`` script does two things.
   between all the EPICS IOC container images and contains the support YAML files
   that tell ``ibek`` how to build support modules inside the container
   environment and how to use them at runtime.
-- it builds the Generic IOC container image locally.
-
-.. note::
-
-    The ``build`` script is a convenience script that is provided in the
-    Generic IOC Template project. It is exactly equivalent to cloning
-    with ``--recursive`` flag and then running ``ec dev build``. Equally,
-    opening a vscode dev container will also build the container for you, but it
-    does require the ``ibek-support`` submodule to be present - using
-    ``--recursive`` flag to git clone ensures this.
+- it builds the Generic IOC container image developer target locally using
+  podman or docker.
 
 Verify the Example IOC Instance is working
 ------------------------------------------