Commit e1e9e3bd authored by Valentin Reis's avatar Valentin Reis

[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
gitlab CI snippets shows how to do this on a nix-enabled runner. Mind
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`
- Use the 'argotest' nix function to provide an environment, among 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 {
```bash
nix-shell -E '
(import( builtins.fetchGit {
url = https://xgitlab.cels.anl.gov/argo/argotest.git;
ref="master";})
}: (import argotest {}).test' --run 'argotk.hs helloworld'
ref="master";
}) {
#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
with an environment in which all the argo components should be in the `PATH`,
along with the `argotk.hs` tool.
### Usage (in three parts)
- [*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 repository. They all have default values.
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 run the 'helloworld' test in an environment that uses a local `nrm`
source, the master `libnrm` branch and a specific revision of the `containers`
branch. We'l'l use the master `argotest` branch for that.
Here, we'll use an environment that uses a local `nrm` source, the master
`libnrm` branch and a specific revision of the `containers` branch. We'l'l use
the master `argotest` branch for that:
```nix
nix-shell -E '{ argotest ? (builtins.fetchGit {
......@@ -53,7 +70,44 @@ nix-shell -E '{ argotest ? (builtins.fetchGit {
}).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.
......@@ -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
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:
......@@ -102,28 +147,6 @@ integration.test:
- 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
- edit `.README.md` in place of README.md.
......
......@@ -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
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`
- Use the 'argotest' nix function to provide an environment, among
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 {
``` {.bash}
nix-shell -E '
(import( builtins.fetchGit {
url = https://xgitlab.cels.anl.gov/argo/argotest.git;
ref="master";})
}: (import argotest {}).test' --run 'argotk.hs helloworld'
ref="master";
}) {
#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 with an environment in which all the argo components should be
in the `PATH`, along with the `argotk.hs` tool.
### Usage (in three parts)
- \[*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
file in this repository. They all have default values.
``` {.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'
```
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 run the 'helloworld' test in an environment that uses a
local `nrm` source, the master `libnrm` branch and a specific revision
of the `containers` branch. We'l'l use the master `argotest` branch for
that.
Here, we'll use an environment that uses a local `nrm` source, the
master `libnrm` branch and a specific revision of the `containers`
branch. We'l'l use the master `argotest` branch for that:
``` {.nix}
nix-shell -E '{ argotest ? (builtins.fetchGit {
......@@ -54,59 +70,8 @@ nix-shell -E '{ argotest ? (builtins.fetchGit {
}).test' --run 'argotk.hs helloworld'
```
*WARNING* 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:
``` {.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:
- \[3\] The `test`environment contains the `argotk.hs` tool, which
runs various operations on the argo stack:
Commands list:
......@@ -153,9 +118,9 @@ Usage: argotk.hs helloworld [--application APP]
[--cmd_err FILE] [--daemon_out FILE]
[--daemon_err FILE] [--nrm_log FILE]
[--message_daemon_stdout STRING]
[--message_daemon_stdout STRING]
[--message_daemon_stdout STRING]
[--message_daemon_stdout STRING]
[--message_daemon_stderr STRING]
[--message_cmd_stdout STRING]
[--message_cmd_stderr STRING]
Test 1: Setup stack and check that a hello world app sends message back to
cmd.
......@@ -183,17 +148,17 @@ Available options:
stdout will be monitored during execution and the
stack will be killed when observing it, returning a
successful exit code.
--message_daemon_stdout STRING
--message_daemon_stderr STRING
The appearance of this character string in the daemon
stderr will be monitored during execution and the
stack will be killed when observing it, returning a
successful exit code.
--message_daemon_stdout STRING
--message_cmd_stdout STRING
The appearance of this character string in the cmd
stdout will be monitored during execution and the
stack will be killed when observing it, returning a
successful exit code. (default: "Hello-Moto")
--message_daemon_stdout STRING
--message_cmd_stderr STRING
The appearance of this character string in the cmd
stderr will be monitored during execution and the
stack will be killed when observing it, returning a
......@@ -201,6 +166,62 @@ Available options:
-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
- 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