Skip to content

Commit 1dc214c

Browse files
gilesknapgilesknap
committed
add zsh
1 parent 9c5f288 commit 1dc214c

File tree

3 files changed

+74
-48
lines changed

3 files changed

+74
-48
lines changed

‎docs/how-to/debug.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
This is an early draft
55
:::
66

7-
This guide will show you how to debug an IOC instance locally. It will use the example IOC made in the [Create an IOC instance](./create-ioc-instance.md) guide. That IOC is called `bl01t-ea-test-02` in the guide but you may have chosen a different name.
7+
This guide will show you how to debug an IOC instance locally. It will use the example IOC made in the [Create an IOC instance](../tutorials/create_ioc) guide. That IOC is called `bl01t-ea-test-02` in the guide but you may have chosen a different name.
88

99
## Setting up
1010

‎docs/reference/configuration.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,3 +30,19 @@ Because all ioc-XXX have the same submodule `ibek-support` and because `/epics/s
3030
"scm.repositories.visible": 12,
3131
```
3232

33+
### zsh shell
34+
35+
For a much richer command line experience, it is recommended to use the zsh shell in vscode, this will work inside Generic IOC devcontainers too. Use the following settings:
36+
37+
```json
38+
"terminal.integrated.profiles.linux": {
39+
"bash": {
40+
"path": "bash",
41+
},
42+
"zsh": {
43+
"path": "zsh"
44+
}
45+
},
46+
"terminal.integrated.defaultProfile.linux": "zsh",
47+
```
48+

‎docs/tutorials/generic_ioc.md

Lines changed: 57 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -52,45 +52,69 @@ Much like creating a new beamline we have a template project that can be used
5252
as the starting point for a new Generic IOC. Again we will create this in
5353
your personal GitHub user space.
5454

55-
Go to the Generic IOC template project at:
5655

57-
<https://github.com/epics-containers/ioc-template>
56+
## Steps
5857

59-
Click on the `Use this template` button and create a new repository called
60-
`ioc-lakeshore340` in your personal GitHub account.
58+
1. Go to your GitHub account home page. Click on 'Repositories' and then 'New', give your new repository the name `ioc-lakeshore340` plus a description, then click 'Create repository'.
6159

62-
As soon as you do this the build in GitHub Actions CI will start building the
63-
project. This will make a container image of the template project, but
64-
not publish it because there is no release tag as yet. You can watch this
65-
by clicking on the `Actions` tab in your new repository.
60+
1. From a command line with your virtual environment activated. Use copier to start to make a new repository like this:
6661

67-
You might think building the template project was a waste of GitHub CPU. But,
68-
this is not so, because of container build cacheing. The next time you build
69-
the project in CI, with your changes, it will re-use most of the steps
70-
and be much faster.
62+
```bash
63+
pip install copier
64+
# this will create the folder ioc-lakeshore340 in the current directory
65+
copier copy gh:epics-containers/ioc-template --trust ioc-lakeshore340
66+
```
67+
1. Answer the copier template questions as follows:
68+
69+
70+
<pre><font color="#5F87AF">🎤</font><b> A name for this project. By convention the name will start with ioc- and</b>
71+
<b>have a lower case suffix of the primary support module. e.g.</b>
72+
<b>ioc-adsimdetector</b>
73+
<b> </b><font color="#FFAF00"><b>ioc-lakeshore340</b></font>
74+
<font color="#5F87AF">🎤</font><b> A One line description of the module</b>
75+
<b> </b><font color="#FFAF00"><b>Generic IOC for the lakeshore 340 temperature controller</b></font>
76+
<font color="#5F87AF">🎤</font><b> Git platform hosting the repository.</b>
77+
<b> </b><font color="#FFAF00"><b>github.com</b></font>
78+
<font color="#5F87AF">🎤</font><b> The GitHub organisation that will contain this repo.</b>
79+
<b> </b><font color="#FFAF00"><b>YOUR_GITHUB_ACCOUNT</b></font>
80+
<font color="#5F87AF">🎤</font><b> Remote URI of the repository.</b>
81+
<b> </b><font color="#FFAF00"><b>[email protected]:YOUR_GITHUB_ACCOUNT/ioc-lakeshore340.git</b></font>
82+
</pre>
83+
84+
1. Make the first commit and push the repository to GitHub.
85+
86+
```bash
87+
cd ioc-lakeshore340
88+
git add .
89+
git commit -m "initial commit"
90+
git push -u origin main
91+
```
92+
93+
1. Get the Generic IOC container built, open the project in vscode and launch the devcontainer.
94+
95+
```bash
96+
./build
97+
# DLS users make sure you have done: module load vscode
98+
code .
99+
# reopen in container
100+
```
101+
102+
As soon as you pushed the project, GitHub Actions CI will start building the project. This will make a container image of the template project, but not publish it because there is no release tag as yet. You can watch this by clicking on the `Actions` tab in your new repository.
103+
104+
You might think building the template project was a waste of GitHub CPU. But, this is not so, because of container build cacheing. The next time you build the project in CI, with your changes, it will re-use most of the steps and be much faster.
71105

72106
## Prepare the New Repo for Development
73107

74108
There are only three places where you need to change the Generic IOC template
75109
to make your own Generic IOC.
76110

77-
1. Dockerfile - add in the support modules you need
78-
2. README.md - change to describe your Generic IOC
79-
3. ibek-support - add new support module recipes into this submodule
111+
1. **Dockerfile** - add in the support modules you need
112+
2. **README.md** - change to describe your Generic IOC
113+
3. **ibek-support** - add new support module recipes into this submodule
80114

81-
To work on this project we will make a local developer container. All
115+
To work on this project we will use local developer container. All
82116
changes and testing will be performed inside this developer container.
83117

84-
To get the developer container up and running:
85-
86-
```bash
87-
git clone [email protected]:<YOUR GITHUB ACCOUNT>/ioc-lakeshore340.git
88-
cd ioc-lakeshore340
89-
./build
90-
code .
91-
# choose "Reopen in Container"
92-
```
93-
94118
Once the developer container is running it is always instructive to have the
95119
`/epics` folder added to your workspace:
96120

@@ -100,34 +124,20 @@ Once the developer container is running it is always instructive to have the
100124
- File -> Save Workspace As...
101125
- Choose the default `/workspaces/ioc-lakeshore340/ioc-lakeshore340.code-workspace`
102126

103-
Note that workspace files are not committed to git. They are specific to your
104-
local development environment. Saving a workspace allows you to reopen the
105-
same set of folders in the developer container, using the *Recent* list shown
106-
when opening a new VSCode window.
127+
Note that workspace files are not committed to git. They are specific to your local development environment. Saving a workspace allows you to reopen the same set of folders in the developer container, using the *Recent* list shown when opening a new VSCode window.
107128

108-
Now is a good time to edit the README.md file and change it to describe your
109-
Generic IOC as you see fit.
129+
Now is a good time to edit the README.md file and change it to describe your Generic IOC as you see fit. However the template will have placed some basic information in there for you already.
110130

111131
## Initial Changes to the Dockerfile
112132

113-
The Dockerfile is the recipe for building the container image. It is a set
114-
of steps that get run inside a container. The starting container filesystem
115-
state is determined by a `FROM` line at the top of the Dockerfile.
133+
The Dockerfile is the recipe for building the container image. It is a set of steps that get run inside a container. The starting container filesystem state is determined by a `FROM` line at the top of the Dockerfile.
116134

117-
In the Generic IOC template the `FROM` line gets a version of the
118-
epics-containers base image. It then demonstrates how to add a support module
119-
to the container image. The `iocStats` support module is added and built
120-
by the template. It is recommended to keep this module as the default
121-
behaviour in Kubernetes is to use `iocStats` to monitor the health of
122-
the IOC.
135+
In the Generic IOC template the `FROM` line gets a version of the epics-containers base image. It then demonstrates how to add a support module to the container image. The `iocStats` support module is added and built by the template. It is recommended to keep this module as the default
136+
behaviour in Kubernetes is to use `iocStats` to monitor the health of the IOC.
123137

124-
Thus you can start adding support modules by adding more `COPY` and `RUN`
125-
lines to the Dockerfile. Just like those for the `iocStats` module.
138+
Thus you can start adding support modules by adding more `COPY` and `RUN` lines to the Dockerfile. Just like those for the `iocStats` module.
126139

127-
The rest of the Dockerfile is boilerplate and for best results you only need
128-
to remove the comment below and replace it with the additional support
129-
modules you need. Doing this means it is easy to adopt changes to the original
130-
template Dockerfile in the future.
140+
The rest of the Dockerfile is boilerplate and for best results you only need to remove the comment below and replace it with the additional support modules you need. Doing this means it is easy to adopt changes to the original template Dockerfile in the future.
131141

132142
```dockerfile
133143
################################################################################

0 commit comments

Comments
 (0)