Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions changelog.d/+first-run-install.doc.md
Original file line number Diff line number Diff line change
@@ -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`.
2 changes: 1 addition & 1 deletion docs/orgmode/howto/find-why-a-build-failed.org
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
1 change: 1 addition & 0 deletions docs/orgmode/howto/index.org
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
85 changes: 85 additions & 0 deletions docs/orgmode/howto/install.org
Original file line number Diff line number Diff line change
@@ -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]]
21 changes: 11 additions & 10 deletions docs/orgmode/tutorials/keep-a-failed-build-log.org
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.
Loading