Commit e1e9e3bd authored by Valentin Reis's avatar Valentin Reis
Browse files

[doc] Readme update.

parent 7489698e
Pipeline #4732 passed with stage
in 13 seconds
...@@ -8,32 +8,49 @@ version(s), as part of development or continuous integration. This ...@@ -8,32 +8,49 @@ version(s), as part of development or continuous integration. This
gitlab CI snippets shows how to do this on a nix-enabled runner. Mind gitlab CI snippets shows how to do this on a nix-enabled runner. Mind
that this setup tracks argotest master. that this setup tracks argotest master.
### Usage ### Usage (tl;dr, I already have nix on my machine.)
- Get Nix: `curl https://nixos.org/nix/install | sh` ```bash
nix-shell -E '
- Use the 'argotest' nix function to provide an environment, among which the (import( builtins.fetchGit {
`argotk.hs` tool, which runs tests. For example, we can run default tests
using pinned `argopkgs` sources like so:
```nix
nix-shell -E '{ argotest ? (builtins.fetchGit {
url = https://xgitlab.cels.anl.gov/argo/argotest.git; url = https://xgitlab.cels.anl.gov/argo/argotest.git;
ref="master";}) ref="master";
}: (import argotest {}).test' --run 'argotk.hs helloworld' }) {
#nrm-src = /path/to/nrm
#libnrm-src = /path/to/nrm
#containers-src = /path/to/nrm
}).test' --run "argotk.hs helloworld"
``` ```
Alternatively, one can get rid of the `--run` option in order to be provided ### Usage (in three parts)
with an environment in which all the argo components should be in the `PATH`,
along with the `argotk.hs` tool. - [*1*] Get Nix: `curl https://nixos.org/nix/install | sh`
- [*2*] Use the ~test~ attribute of the argotest' nix attribute set to enter a
test environment. For example, we can run default tests on the
"argopkgs-pinned" version of argo components using:
```bash
nix-shell -E '
let
argotest-src =
builtins.fetchGit {
url = https://xgitlab.cels.anl.gov/argo/argotest.git;
ref="master";
};
argotest = import argotest-src {};
in
argotest.test'
```
The arguments to the argotest function are defined in the default.nix file in This environment has all the necessary Argo components in its PATH. The
this repository. They all have default values. argotest function has various arguments, defined in the default.nix file at the
rooto of this repository. They all have default values. For a more involved
example, let's get a custom test environment.
For a more involved example, let's run a test in a custom environment. Here, Here, we'll use an environment that uses a local `nrm` source, the master
we'll run the 'helloworld' test in an environment that uses a local `nrm` `libnrm` branch and a specific revision of the `containers` branch. We'l'l use
source, the master `libnrm` branch and a specific revision of the `containers` the master `argotest` branch for that:
branch. We'l'l use the master `argotest` branch for that.
```nix ```nix
nix-shell -E '{ argotest ? (builtins.fetchGit { nix-shell -E '{ argotest ? (builtins.fetchGit {
...@@ -53,7 +70,44 @@ nix-shell -E '{ argotest ? (builtins.fetchGit { ...@@ -53,7 +70,44 @@ nix-shell -E '{ argotest ? (builtins.fetchGit {
}).test' --run 'argotk.hs helloworld' }).test' --run 'argotk.hs helloworld'
``` ```
*WARNING* There are a few things one has to be aware of using this workflow: - [3] The `test`environment contains the `argotk.hs` tool, which runs various
operations on the argo stack:
Commands list:
```{.bash}
argotk.hs --help
```
Output:
```{.txt pipe="sh"}
root/argotk/argotk.hs --help
```
Detailed help:
```{.bash}
argotk.hs helloworld --help
```
Output:
```{.txt pipe="sh"}
root/argotk/argotk.hs helloworld --help
```
####Misc
Alternatively, one can use the `--run` option to run a test directly:
```bash
nix-shell -E '
(import( builtins.fetchGit {
url = https://xgitlab.cels.anl.gov/argo/argotest.git;
ref="master";
}) {}).test' --run "argotk.hs helloworld"
```
#### WARNINGS
There are a few things one has to be aware of using this workflow:
- Builds may fail if the local source repositories are dirty with old build files. - Builds may fail if the local source repositories are dirty with old build files.
...@@ -64,15 +118,6 @@ nix-shell -E '{ argotest ? (builtins.fetchGit { ...@@ -64,15 +118,6 @@ nix-shell -E '{ argotest ? (builtins.fetchGit {
minutes by default. Use a local checkout if you need to modify some of these minutes by default. Use a local checkout if you need to modify some of these
sources on the fly: sources on the fly:
```nix
nix-shell -E '{ argotest ? /path/to/argotest }:
(import argotest {
nrm-src = /path/to/nrm;
# libnrm-src left at default argument value (inherits from argopkgs)
# containers-src left at default argument value (inherits from argopkgs)
}).test' --run 'argotk.hs helloworld'
```
### Example CI setup ### Example CI setup
For example, we could setup the CI for the `containers` repo like: For example, we could setup the CI for the `containers` repo like:
...@@ -102,28 +147,6 @@ integration.test: ...@@ -102,28 +147,6 @@ integration.test:
- integration - integration
``` ```
### Argotk.hs usage:
Commands list:
```{.bash}
argotk.hs --help
```
Output:
```{.txt pipe="sh"}
root/argotk/argotk.hs --help
```
Detailed help:
```{.bash}
argotk.hs helloworld --help
```
Output:
```{.txt pipe="sh"}
root/argotk/argotk.hs helloworld --help
```
### Hacking ### Hacking
- edit `.README.md` in place of README.md. - edit `.README.md` in place of README.md.
......
...@@ -8,33 +8,49 @@ version(s), as part of development or continuous integration. This ...@@ -8,33 +8,49 @@ version(s), as part of development or continuous integration. This
gitlab CI snippets shows how to do this on a nix-enabled runner. Mind gitlab CI snippets shows how to do this on a nix-enabled runner. Mind
that this setup tracks argotest master. that this setup tracks argotest master.
### Usage ### Usage (tl;dr, I already have nix on my machine.)
- Get Nix: `curl https://nixos.org/nix/install | sh` ``` {.bash}
nix-shell -E '
- Use the 'argotest' nix function to provide an environment, among (import( builtins.fetchGit {
which the `argotk.hs` tool, which runs tests. For example, we can
run default tests using pinned `argopkgs` sources like so:
``` {.nix}
nix-shell -E '{ argotest ? (builtins.fetchGit {
url = https://xgitlab.cels.anl.gov/argo/argotest.git; url = https://xgitlab.cels.anl.gov/argo/argotest.git;
ref="master";}) ref="master";
}: (import argotest {}).test' --run 'argotk.hs helloworld' }) {
#nrm-src = /path/to/nrm
#libnrm-src = /path/to/nrm
#containers-src = /path/to/nrm
}).test' --run "argotk.hs helloworld"
``` ```
Alternatively, one can get rid of the `--run` option in order to be ### Usage (in three parts)
provided with an environment in which all the argo components should be
in the `PATH`, along with the `argotk.hs` tool. - \[*1*\] Get Nix: `curl https://nixos.org/nix/install | sh`
- \[*2*\] Use the ~test~ attribute of the argotest' nix attribute set
to enter a test environment. For example, we can run default tests
on the "argopkgs-pinned" version of argo components using:
The arguments to the argotest function are defined in the default.nix ``` {.bash}
file in this repository. They all have default values. nix-shell -E '
let
argotest-src =
builtins.fetchGit {
url = https://xgitlab.cels.anl.gov/argo/argotest.git;
ref="master";
};
argotest = import argotest-src {};
in
argotest.test'
```
This environment has all the necessary Argo components in its PATH. The
argotest function has various arguments, defined in the default.nix file
at the rooto of this repository. They all have default values. For a
more involved example, let's get a custom test environment.
For a more involved example, let's run a test in a custom environment. Here, we'll use an environment that uses a local `nrm` source, the
Here, we'll run the 'helloworld' test in an environment that uses a master `libnrm` branch and a specific revision of the `containers`
local `nrm` source, the master `libnrm` branch and a specific revision branch. We'l'l use the master `argotest` branch for that:
of the `containers` branch. We'l'l use the master `argotest` branch for
that.
``` {.nix} ``` {.nix}
nix-shell -E '{ argotest ? (builtins.fetchGit { nix-shell -E '{ argotest ? (builtins.fetchGit {
...@@ -54,59 +70,8 @@ nix-shell -E '{ argotest ? (builtins.fetchGit { ...@@ -54,59 +70,8 @@ nix-shell -E '{ argotest ? (builtins.fetchGit {
}).test' --run 'argotk.hs helloworld' }).test' --run 'argotk.hs helloworld'
``` ```
*WARNING* There are a few things one has to be aware of using this - \[3\] The `test`environment contains the `argotk.hs` tool, which
workflow: runs various operations on the argo stack:
- Builds may fail if the local source repositories are dirty with old
build files.
- Builds may fail if `PWD` is in a `nosuid`-enabled filesystem.
- Without using the `rev` argument, the `builtins.fetchGit` nix
command prefetches and buffers its output, with an expiration time
that ranges ten minutes by default. Use a local checkout if you need
to modify some of these sources on the fly:
``` {.nix}
nix-shell -E '{ argotest ? /path/to/argotest }:
(import argotest {
nrm-src = /path/to/nrm;
# libnrm-src left at default argument value (inherits from argopkgs)
# containers-src left at default argument value (inherits from argopkgs)
}).test' --run 'argotk.hs helloworld'
```
### Example CI setup
For example, we could setup the CI for the `containers` repo like:
``` {.yml}
integration.test:
stage: test
script:
- nix-shell -E '{ argotest ? (builtins.fetchGit {
url = https://xgitlab.cels.anl.gov/argo/argotest.git;
ref="master";})
}:
(import argotest { containers-src = ./. ; }).test'
--run 'argotk.hs helloworld'
artifacts:
paths:
- argotest/_output/cmd_err.log
- argotest/_output/cmd_out.log
- argotest/_output/daemon_out.log
- argotest/_output/daemon_out.log
- argotest/_output/nrm.log
- argotest/_output/time.log
expire_in: 1 week
except:
- /^wip\/.*/
- /^WIP\/.*/
tags:
- integration
```
### Argotk.hs usage:
Commands list: Commands list:
...@@ -153,9 +118,9 @@ Usage: argotk.hs helloworld [--application APP] ...@@ -153,9 +118,9 @@ Usage: argotk.hs helloworld [--application APP]
[--cmd_err FILE] [--daemon_out FILE] [--cmd_err FILE] [--daemon_out FILE]
[--daemon_err FILE] [--nrm_log FILE] [--daemon_err FILE] [--nrm_log FILE]
[--message_daemon_stdout STRING] [--message_daemon_stdout STRING]
[--message_daemon_stdout STRING] [--message_daemon_stderr STRING]
[--message_daemon_stdout STRING] [--message_cmd_stdout STRING]
[--message_daemon_stdout STRING] [--message_cmd_stderr STRING]
Test 1: Setup stack and check that a hello world app sends message back to Test 1: Setup stack and check that a hello world app sends message back to
cmd. cmd.
...@@ -183,17 +148,17 @@ Available options: ...@@ -183,17 +148,17 @@ Available options:
stdout will be monitored during execution and the stdout will be monitored during execution and the
stack will be killed when observing it, returning a stack will be killed when observing it, returning a
successful exit code. successful exit code.
--message_daemon_stdout STRING --message_daemon_stderr STRING
The appearance of this character string in the daemon The appearance of this character string in the daemon
stderr will be monitored during execution and the stderr will be monitored during execution and the
stack will be killed when observing it, returning a stack will be killed when observing it, returning a
successful exit code. successful exit code.
--message_daemon_stdout STRING --message_cmd_stdout STRING
The appearance of this character string in the cmd The appearance of this character string in the cmd
stdout will be monitored during execution and the stdout will be monitored during execution and the
stack will be killed when observing it, returning a stack will be killed when observing it, returning a
successful exit code. (default: "Hello-Moto") successful exit code. (default: "Hello-Moto")
--message_daemon_stdout STRING --message_cmd_stderr STRING
The appearance of this character string in the cmd The appearance of this character string in the cmd
stderr will be monitored during execution and the stderr will be monitored during execution and the
stack will be killed when observing it, returning a stack will be killed when observing it, returning a
...@@ -201,6 +166,62 @@ Available options: ...@@ -201,6 +166,62 @@ Available options:
-h,--help Show this help text -h,--help Show this help text
``` ```
\#\#\#\#Misc
Alternatively, one can use the `--run` option to run a test directly:
``` {.bash}
nix-shell -E '
(import( builtins.fetchGit {
url = https://xgitlab.cels.anl.gov/argo/argotest.git;
ref="master";
}) {}).test' --run "argotk.hs helloworld"
```
#### WARNINGS
There are a few things one has to be aware of using this workflow:
- Builds may fail if the local source repositories are dirty with old
build files.
- Builds may fail if `PWD` is in a `nosuid`-enabled filesystem.
- Without using the `rev` argument, the `builtins.fetchGit` nix
command prefetches and buffers its output, with an expiration time
that ranges ten minutes by default. Use a local checkout if you need
to modify some of these sources on the fly:
### Example CI setup
For example, we could setup the CI for the `containers` repo like:
``` {.yml}
integration.test:
stage: test
script:
- nix-shell -E '{ argotest ? (builtins.fetchGit {
url = https://xgitlab.cels.anl.gov/argo/argotest.git;
ref="master";})
}:
(import argotest { containers-src = ./. ; }).test'
--run 'argotk.hs helloworld'
artifacts:
paths:
- argotest/_output/cmd_err.log
- argotest/_output/cmd_out.log
- argotest/_output/daemon_out.log
- argotest/_output/daemon_out.log
- argotest/_output/nrm.log
- argotest/_output/time.log
expire_in: 1 week
except:
- /^wip\/.*/
- /^WIP\/.*/
tags:
- integration
```
### Hacking ### Hacking
- edit `.README.md` in place of README.md. - edit `.README.md` in place of README.md.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment