switch /repos to /workspaces

Author: gilesknap

docs/user/index.rst

@@ -22,7 +22,6 @@ side-bar.
             tutorials/ioc_changes1
             tutorials/ioc_changes2
             tutorials/ioc_changes3
-            tutorials/ioc_changes4
             tutorials/generic_ioc
             tutorials/debug_generic_ioc
             tutorials/test_generic_ioc

docs/user/reference/ioc_helm_chart.rst

@@ -58,7 +58,7 @@ in this folder and what you would need to change in your new IOC instance:
 
 -   ``config`` this folder contains any files unique to this IOC instance. At
     runtime on the cluster when the Generic IOC image is running it will see
-    these files as mounted into the folder ``/repos/epics/ioc/config``.
+    these files as mounted into the folder ``/workspaces/epics/ioc/config``.
     In this case we have an EPICS startup script ``st.cmd`` only
     and the default behaviour is just to run the IOC binary and pass it
     ``st.cmd``.

docs/user/tutorials/create_beamline.rst

@@ -66,7 +66,7 @@ We will then step through the changes that are required to make it your own.
 NOTE: for these tutorials we will use your personal GitHub Account to
 store everything we do, all source repositories and container images. For
 production, each facility will need its own policy for where to store these
-assets. See `../explanations/repositories`.
+assets. See ``../explanations/workspacesitories``.
 
 Steps
 -----

docs/user/tutorials/debug_generic_ioc.rst

@@ -44,7 +44,7 @@ command.
 
 .. code-block:: bash
 
-    cd /repos/epics/support/adurl
+    cd /workspaces/epics/support/adurl
     make
 
 You should see the same error again.
@@ -81,7 +81,7 @@ need to set the variable ``GRAPHICSMAGICK_INCLUDE`` in
 We can see from the ``apt-file`` output that the header file is in
 ``/usr/include/GraphicsMagick`` which is not a default include path.
 Therefore we need to edit this file inside our Generic IOC container:
-``/repos/epics/support/adurl/configure/CONFIG_SITE.linux-x86_64.Common``
+``/workspaces/epics/support/adurl/configure/CONFIG_SITE.linux-x86_64.Common``
 
 .. _CONFIG_SITE.local: https://areadetector.github.io/areaDetector/install_guide.html#edit-config-site-local-and-optionally-config-site-local-epics-host-arch
 
@@ -95,8 +95,8 @@ you like from the Ubuntu repositories.
 
 HOWEVER, there is a much easier way ...
 
-When you launch containers with ``ec`` commands the ``/repos`` folder is
-synchronized to a local folder ioc-XXX/repos and that is mounted into the
+When you launch containers with ``ec`` commands the ``/workspaces`` folder is
+synchronized to a local folder ioc-XXX/workspaces and that is mounted into the
 container. This means that you can edit files in the container using VSCode.
 The mounted repos folder also ensures that any changes you make inside the
 container are saved between invocations of the container.

docs/user/tutorials/dev_container.rst

@@ -230,50 +230,57 @@ The above is true because your project folder ioc-adsimdetector is mounted into
 the container's filesystem with a bind mount at the same place that the
 ioc files were originally placed by the container build.
 
-epics-containers devcontainers have carefully curated host filesystem mounts
-that allow them to look as similar as possible to the runtime container but
-at the same time preserve any changes that you make in the host file system.
-This is important because the container filesystem is temporary and will be
+epics-containers devcontainers have carefully curated host filesystem mounts.
+This allows the developer environment to look as similar as possible to the
+runtime container.
+It also will preserve any important changes that you make in the host file system.
+This is essential because the container filesystem is temporary and will bed
 destroyed when the container is rebuilt or deleted.
 
-The IOC code is entirely boilerplate boilerplate, the ``src/Makefile``
+See `container-layout`_ for details of which host folders are mounted into the
+container.
+
+The IOC code is entirely boilerplate, the ``/epics/ioc/iocApp/src/Makefile``
 determines which dbd and lib files to link by including two files that
-ibek generated during the container build namely
+``ibek`` generated during the container build namely
 ``/epics/support/configure/lib_list`` and ``/epics/support/configure/dbd_list``.
-
-You can go and take a look at the Makefile in
-``/epics/ioc/iocApp/src/Makefile`` to see how this is done.
+Although all Generic IOCs derived from ioc-template start out with the same
+generic source in ``iocApp/src``, you are free to change them if there is
+a need for different compilation options etc.
 
 The Generic IOC should now be ready to run inside of the container. To do this:
 
 .. code-block:: bash
 
-   cd ioc
    ./start.sh
 
 You will just see the default output of a Generic IOC that has no Instance
-configuration. Next we will add some instance configuration from one of the
+configuration. Hit ``Ctrl-C`` to stop the this default script.
+
+Next we will add some instance configuration from one of the
 IOC instances in the ``bl01t`` beamline.
 
-Let's now add some other folders to our VSCode workspace to make it easier to
-work with ``bl01t`` and to investigate the container.
+To do this we will add some other folders to our VSCode workspace to make it
+easier to work with ``bl01t`` and to investigate the container filesystem.
 
 Adding the Beamline to the Workspace
 ------------------------------------
 
 To meaningfully test the Generic IOC we will need an instance to test it
-against. We will use the ``bl01t`` beamline that you already made. The container
-has been configured to mount some useful local files from the user's home directory,
-including the parent folder of the workspace as ``/repos`` so we can work on
+against. We will use the ``bl01t`` beamline that you already made. The devcontainer
+has been configured to mount some useful host folders into the container
+including the parent folder of the workspace as ``/workspaces`` so we can work on
 multiple peer projects.
 
 In VSCode click the ``File`` menu and select ``Add Folder to Workspace``.
-Navigate to ``/repos`` and you will see all the peers of your ``ioc-adsimdetector``
+Navigate to ``/workspaces`` and you will see all the peers of your ``ioc-adsimdetector``
 folder (see `container-layout` below). Choose the ``bl01t`` folder and add it to the
-workspace - you may see an error but if so clicking "reload window" will
+workspace - you may see an error but if so clicking "Cancel" will
 clear it.
 
-Also take this opportunity to add the folder ``/epics`` to the workspace.
+Also take this opportunity to add the folder ``/epics`` to the workspace. This
+is the root folder in which all of the EPICS source and built files are
+located.
 
 .. note::
 
@@ -284,7 +291,7 @@ Also take this opportunity to add the folder ``/epics`` to the workspace.
   built by the container and should be considered immutable. We will learn
   how to work on support modules in later tutorials. This error should only
   be seen on first launch. podman users will have no such problem because they
-  will be root inside the container and root build the container.
+  will be root inside the container and root built the container.
 
 You can now easily browse around the ``/epics`` folder and see all the
 support modules and epics-base. This will give you a feel for the layout of
@@ -309,10 +316,6 @@ host. i.e. the root folder under which your projects are all cloned):
      - N/A
      - compiled epics-base
 
-   * - /epics/ioc-adsimdetector
-     - WS/ioc-adsimdetector
-     - Source repository for the Generic IOC
-
    * - /epics/ioc
      - WS/ioc-adsimdetector/ioc
      - soft link to IOC source tree
@@ -329,10 +332,19 @@ host. i.e. the root folder under which your projects are all cloned):
      - N/A
      - all OPI files (generated or copied from support)
 
-   * - /repos
+   * - /workspaces
      - WS
      - all peers to Generic IOC source repo
 
+   * - /workspaces/ioc-adsimdetector
+     - WS/ioc-adsimdetector
+     - Generic IOC source repo (in this example)
+
+   * - /epics/generic-source
+     - WS/ioc-adsimdetector
+     - A second - fixed location mount of the Generic IOC source repo
+
+
 .. _choose-ioc-instance:
 
 Choose the IOC Instance to Test
@@ -346,7 +358,7 @@ Try the following:
 
    cd /epics/ioc
    rm -r config
-   ln -s /repos/bl01t/iocs/bl01t-ea-ioc-02/config .
+   ln -s /workspaces/bl01t/iocs/bl01t-ea-ioc-02/config .
    # check the ln worked
    ls -l config
    ./start.sh

docs/user/tutorials/generic_ioc.rst

@@ -246,7 +246,7 @@ follows:
 - ``RELEASE.local`` - This tells the ADURL build where to find
   the support modules that it depends on. epics-containers maintains a
   global release file that is used by all support modules and IOCs. It
-  located at ``/repos/epics/support/configure/RELEASE``. Therefore we
+  located at ``/workspaces/epics/support/configure/RELEASE``. Therefore we
   place a reference to this file in the RELEASE.local file. Whenever
   ``python3 modules.py install`` is run it will update the global release
   file and also fixup any ``SUPPORT=`` lines in all ``configure/RELEASE*``

docs/user/tutorials/ibek.rst

@@ -83,7 +83,7 @@ STEPS:
 - ec dev build
 - ec dev launch
 - inside the container:
-  - cd /repos/epics/ioc
+  - cd /workspaces/epics/ioc
   - start.sh
 
 .. figure:: ../images/ibek-defs-notes.png

docs/user/tutorials/ioc_changes1.rst

@@ -86,7 +86,7 @@ If you see the value 1 then your change is working.
     is required for running OPI tools on the host (TODO add link to solution).
 
 Because of the symlink between ``/epics/ioc/config`` and
-``/repos/bl01t/iocs/bl01t-ea-ioc-02/config`` the same files you are testing
+``/workspaces/bl01t/iocs/bl01t-ea-ioc-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.:
 
@@ -105,7 +105,7 @@ committed and pushed to the bl01t repo. i.e.:
 
 The above steps were performed on a host terminal because we are using ``ec``.
 However all of the steps except for the ``ec`` command could have been done
-*inside* the devcontainer starting with ``cd /repos/bl01t``.
+*inside* the devcontainer starting with ``cd /workspaces/bl01t``.
 
 We choose not to have ``ec`` installed inside of the devcontainer because
 that would involve containers in containers which adds too much complexity.