diff --git a/README.md b/README.md index bb7ce8f..b65a7a9 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,9 @@ It passes `--output-style=basic`, because EasyBuild 5.3 and later fold that path ## Install -Each release has a static binary for `x86_64` and `aarch64` Linux, with `SHA256SUMS`. +Each [release](https://github.com/stackhands/eb-keep-logs/releases/latest) has a static binary for `x86_64` and `aarch64` Linux, with `SHA256SUMS`. +The latest tag is v0.2.1. +The main branch fixes keeping logs when EasyBuild 5.3 or later folds the path from `eb --last-log` on a pipe; install from source until a newer release includes that fix. It needs nothing but `eb`: ```bash diff --git a/changelog.d/+first-run-install.doc.md b/changelog.d/+first-run-install.doc.md new file mode 100644 index 0000000..a1dd4d6 --- /dev/null +++ b/changelog.d/+first-run-install.doc.md @@ -0,0 +1 @@ +The install how-to, the README release pointer and the tutorial install from source so `failed` works on EasyBuild 5.3 or newer and the next-step commands exist on `PATH`. \ No newline at end of file diff --git a/docs/orgmode/howto/find-why-a-build-failed.org b/docs/orgmode/howto/find-why-a-build-failed.org index dac0fa0..c7fa3ee 100644 --- a/docs/orgmode/howto/find-why-a-build-failed.org +++ b/docs/orgmode/howto/find-why-a-build-failed.org @@ -9,7 +9,7 @@ Use this after a run in which builds failed, to see for each the EasyBuild step ** Before you start -- =eb-keep-logs= built with Zig, as =zig build -Drelease=true= in its repository builds it, on your =PATH=: the shell script has no =why= or =history=. +- =eb-keep-logs= on your =PATH= as the release binary or a Zig build; the shell script in the repository has no =why= or =history=. - A log tree, here =~/build-logs=, whose runs are named by their date and time, =YYYYMMDD_HHMMSS=, as [[file:call-from-a-pipeline.org][Call eb-keep-logs from a build pipeline]] makes them. A run keeps each build's =NAME.stdout.log= and, for a failed build, =NAME.failed.ebout.log=, in its own directory or in a directory per target, as eb-pipeline keeps them. diff --git a/docs/orgmode/howto/index.org b/docs/orgmode/howto/index.org index fc71108..47ab9a8 100644 --- a/docs/orgmode/howto/index.org +++ b/docs/orgmode/howto/index.org @@ -11,6 +11,7 @@ The title names the task. .. toctree:: :maxdepth: 1 + install call-from-a-pipeline find-why-a-build-failed who-loaded-a-module diff --git a/docs/orgmode/howto/install.org b/docs/orgmode/howto/install.org new file mode 100644 index 0000000..1889f4e --- /dev/null +++ b/docs/orgmode/howto/install.org @@ -0,0 +1,85 @@ +#+title: Install eb-keep-logs + +Install the =eb-keep-logs= program for your account, from a release or from source. +A site that installs it as a module can load that module instead and skip this page. + +Release v0.2.1 is the latest tag. +The code on the main branch also has =used= for prefix retention checks and fixes =failed= when EasyBuild 5.3 or later folds the path =eb --last-log= prints on a pipe. +Until the next release, install from source for those changes, or to run this tutorial on EasyBuild 5.3 or newer. + +* Before you start + +- A Linux host on x86_64 or aarch64. + The release binary is linked statically against musl. +- =eb= on =PATH= for =failed=. +- For a build from source, Zig 0.17.1 and git. +- =~/.local/bin= on your =PATH=. + +* Install a release + +1. Download the binary for this host's architecture and the release checksums, and check the binary: + + #+begin_src bash + v=0.2.1; f=eb-keep-logs-$v-$(uname -m)-linux-musl + mkdir -p ~/.local/bin && cd ~/.local/bin + curl -fsSLO "https://github.com/stackhands/eb-keep-logs/releases/download/v$v/$f" + curl -fsSLO "https://github.com/stackhands/eb-keep-logs/releases/download/v$v/SHA256SUMS" + sha256sum -c --ignore-missing SHA256SUMS + #+end_src + + #+begin_example + eb-keep-logs-0.2.1-x86_64-linux-musl: OK + #+end_example + +2. Name the binary =eb-keep-logs=: + + #+begin_src bash + install -m 0755 "$f" eb-keep-logs + #+end_src + +Release 0.2.1 runs =failed=, =rotate=, =why= and =history=. +The main branch also adds =used=. +The shell script in the repository runs =failed= and =rotate= only. + +* Install from source + +Build the main branch with Zig 0.17.1 and install the binary: + +#+begin_src bash +git clone https://github.com/stackhands/eb-keep-logs.git +cd eb-keep-logs +zig build -Drelease=true +install -D -m 755 zig-out/bin/eb-keep-logs ~/.local/bin/eb-keep-logs +#+end_src + +* Check that it worked + +#+begin_src bash +command -v eb-keep-logs +eb-keep-logs --version +eb-keep-logs why --help | head -n 1 +#+end_src + +#+begin_example +/home/alice/.local/bin/eb-keep-logs +eb-keep-logs 0.2.1 (x86_64-linux-musl, zig 0.17.1) +Usage: eb-keep-logs why [OPTIONS] [RUN] +#+end_example + +The version line shows the release when you install a release file; a source build shows its commit. + +* If it fails + +| Message | Cause | What to do | +|-------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------+----------------------------------------------------------------------------| +| =eb-keep-logs-0.2.1-x86_64-linux-musl: FAILED= and =sha256sum: WARNING: 1 computed checksum did NOT match= | The file is not the one the checksums name. | Download again, and check again. | +| =curl: (22) The requested URL returned error: 404= | The architecture is neither x86_64 nor aarch64, or =v= names no release. | Install from source. | +| =failed= keeps nothing on EasyBuild 5.3 or newer | Release 0.2.1 predates the =--output-style=basic= fix for folded =eb --last-log= paths. | Install from source, or use the shell script from the same commit. | +| The shell does not find =eb-keep-logs= | =~/.local/bin= is not on =PATH=. | Add it in your shell startup file. | +| =why= or =history= is not a subcommand of this script= | The shell script is on =PATH= ahead of the release binary. | Install the release binary or a Zig build, and put it first on =PATH=. | + +* Related + +- [[file:../tutorials/keep-a-failed-build-log.org][Keep a failed build's logs]] +- [[file:find-why-a-build-failed.org][Find why a build failed]] +- [[file:../reference/cli.org][The eb-keep-logs command]] \ No newline at end of file diff --git a/docs/orgmode/tutorials/keep-a-failed-build-log.org b/docs/orgmode/tutorials/keep-a-failed-build-log.org index 48fc48c..02a51e2 100644 --- a/docs/orgmode/tutorials/keep-a-failed-build-log.org +++ b/docs/orgmode/tutorials/keep-a-failed-build-log.org @@ -25,23 +25,24 @@ Every command runs as an ordinary user on a Linux machine with EasyBuild 5. ** Install eb-keep-logs -# The 0.2.1 release binary keeps no log when EasyBuild 5.3 or later folds the -# path eb --last-log prints, which later commits fix. Install the release -# binary here once a release after 0.2.1 is out, and run the tutorial again. -Download =eb-keep-logs=, the shell script, at a fixed commit into =~/.local/bin=, and make it executable: +Install the program from the main branch so =failed= keeps the log on EasyBuild 5.3 or newer and the commands in the [[file:../howto/find-why-a-build-failed.org][Next steps]] exist: #+begin_src bash -curl -sSfL -o ~/.local/bin/eb-keep-logs \ - https://raw.githubusercontent.com/stackhands/eb-keep-logs/5ceaead6b7f1ab7a0f5ddcc0fad14f6d3a51f5cc/eb-keep-logs -chmod 0755 ~/.local/bin/eb-keep-logs +git clone https://github.com/stackhands/eb-keep-logs.git +cd eb-keep-logs +zig build -Drelease=true +install -D -m 755 zig-out/bin/eb-keep-logs ~/.local/bin/eb-keep-logs command -v eb-keep-logs +eb-keep-logs --version #+end_src #+begin_example /home/alice/.local/bin/eb-keep-logs +eb-keep-logs 0.2.1 (x86_64-linux-musl, zig 0.17.1, abc1234) #+end_example -The download is the shell script. It runs =failed= and =rotate=. =why= and =history= are in the Zig build only, and the script says so when it is asked for them. [[file:../howto/find-why-a-build-failed.org][Find why a build failed]] says to build that program with =zig build -Drelease=true= and to put it first on =PATH=, ahead of this script. +[[file:../howto/install.org][Install eb-keep-logs]] has the release binary when you do not need the main-branch fix. +The shell script in the repository runs =failed= and =rotate= only; =why= and =history= are in the Zig build only, and the script says so when it is asked for them. ** Make a directory for this run's logs @@ -186,9 +187,9 @@ cat "$LOGDIR/.licensed-logs" ** Next steps -- [[file:../howto/find-why-a-build-failed.org][Find why a build failed]], which needs the Zig build, not this script +- [[file:../howto/find-why-a-build-failed.org][Find why a build failed]] - [[file:../howto/call-from-a-pipeline.org][Call eb-keep-logs from a build pipeline]] - [[file:../howto/rotate-a-log-tree.org][Rotate a log tree]] - [[file:../reference/cli.org][The eb-keep-logs command]] -Checked with EasyBuild 5.4.2, Lmod 8.6.19 and eb-keep-logs at commit 5ceaead on 2026-11-16. +Checked with EasyBuild 5.4.2, Lmod 8.6.19 and eb-keep-logs built from main on 2026-11-17.