[← README](../../README.md) · [Docs index](../README.md) · [Systems](README.md)

# NetBSD

Both apps run on NetBSD. The terminal app, `coxswain`, is one binary that needs nothing beyond
the base system, built and tested on every change with pkgsrc's Rust. The desktop app,
`coxswain-gui`, is **experimental** on NetBSD: it builds, its tests pass and it starts under X11
in CI, with WebKitGTK from pkgsrc's binary packages, but it has had little use on real desktops
yet ([what experimental means](#the-desktop-app-what-experimental-means)).

Release builds are for **NetBSD 10 on amd64**, built and tested on NetBSD 10.1. NetBSD keeps
its libraries' interfaces, so the 10.1 build should run on 11 as well, but CI does not test 11.

![The desktop app on NetBSD 10.1 in CI, theme Cyber: the first-run guide's Two panels page over the panes, both showing the Coxswain checkout, and the sidebar's drive System with its free space](../screenshots/netbsd-gui.png)
*The desktop app on NetBSD 10.1, as CI starts it under Xvfb: the first-run guide over the
panes.*

## Contents

- [Install with one line](#install-with-one-line)
- [What the script does](#what-the-script-does)
- [Install by hand](#install-by-hand)
- [The packages, and what each is for](#the-packages-and-what-each-is-for)
- [Starting the apps](#starting-the-apps)
- [The search helper](#the-search-helper)
- [How NetBSD differs from Linux here](#how-netbsd-differs-from-linux-here)
- [Updating and uninstalling](#updating-and-uninstalling)
- [Building from source](#building-from-source)
- [The desktop app: what experimental means](#the-desktop-app-what-experimental-means)
- [The pkgsrc package](#the-pkgsrc-package)
- [Questions](#questions)

## Install with one line

```sh
ftp -o - https://raw.githubusercontent.com/mwo-dk/coxswain/master/install/install-unix.sh | sh
```

NetBSD's `ftp(1)` speaks HTTPS. The script is plain `sh`, the same one that installs on OpenBSD
and illumos. It asks before it does anything that needs root, gets root rights from `sudo` or
`doas` (either from pkgsrc) when you are not root, and checks every download against its
SHA-256 sum (`cksum -a sha256`). To read it first:

```sh
ftp https://raw.githubusercontent.com/mwo-dk/coxswain/master/install/install-unix.sh
less install-unix.sh
sh install-unix.sh
```

| Option | Does |
|---|---|
| `--terminal-only` | Only the terminal app, without the desktop app and its packages |
| `--prefix DIR` | Install into `DIR`. Without it the script uses the place Coxswain is already in, or asks: `/usr/local` for every user, or `~/.local` for you alone |
| `--version v2.8.0` | That release instead of the latest |
| `--from DIR` | Install from release archives already in `DIR`, without downloading |
| `--yes` | Answer yes to every question |
| `--uninstall` | Remove what the script installed |

Options go after `sh -s --` when the script comes through a pipe:
`ftp -o - …/install-unix.sh | sh -s -- --prefix ~/.local`.

## What the script does

1. Asks GitHub for the latest release and downloads
   `coxswain-terminal-<version>-x86_64-unknown-netbsd.tar.gz` and its `.sha256`, and stops if
   the sum does not match.
2. Installs `bin/coxswain`, the `cox` link and the manual page `coxswain(1)` under the prefix
   (`/usr/local/man/man1`). Coxswain is not a pkgsrc package, so it stays out of `/usr/pkg`,
   which belongs to `pkgin` and `pkg_add`.
3. With the prefix `/usr/local` it also installs the rc.d script `/etc/rc.d/coxswain_index`,
   which stays off until rc.conf turns it on ([the search helper](#the-search-helper)).
4. For the desktop app, checks which packages are missing, prints the `pkgin install` line, and
   runs it through `sudo` or `doas` when you say yes. Without `webkit-gtk41` it leaves the
   desktop app out and says so; the terminal app is installed either way.
5. Downloads `coxswain-desktop-<version>-x86_64-unknown-netbsd.tar.gz` the same way and
   installs `bin/coxswain-gui`, `share/applications/coxswain.desktop` and the icon.
6. Lists the optional packages that are not installed, with what each adds.

`man coxswain` finds the manual: NetBSD's `/etc/man.conf` looks in `/usr/local/man`. With the
prefix `~/.local`, set `MANPATH="$HOME/.local/man:"` (the trailing colon keeps the system's).

## Install by hand

```sh
v=v2.8.0
t=x86_64-unknown-netbsd
ftp https://github.com/mwo-dk/coxswain/releases/download/$v/coxswain-terminal-$v-$t.tar.gz
ftp https://github.com/mwo-dk/coxswain/releases/download/$v/coxswain-terminal-$v-$t.tar.gz.sha256
cksum -a sha256 coxswain-terminal-$v-$t.tar.gz; cat coxswain-terminal-$v-$t.tar.gz.sha256
tar xzf coxswain-terminal-$v-$t.tar.gz
cd coxswain-terminal-$v-$t
install -m 755 coxswain /usr/local/bin/
ln -sf coxswain /usr/local/bin/cox
install -m 644 coxswain.1 /usr/local/man/man1/
install -m 555 coxswain_index /etc/rc.d/
```

(as root). The two sums printed must be the same. Every download can also be checked against
the release's `SHA256SUMS` and its signed provenance ([Security](../reference/security.md)).

## The packages, and what each is for

The terminal app needs no packages. The desktop app needs `webkit-gtk41`. What adds to them,
from pkgsrc with `pkgin install`:

| Package | For |
|---|---|
| `webkit-gtk41` | The desktop app's window content: WebKitGTK with the 4.1 API; brings `gtk3+` and `libsoup3`. Desktop app, required; it needs the base system's X sets (`xbase`, which a system installed with X has) |
| `gst-plugins1-good` | Video and sound in the desktop app's preview pane; without it a notice says what to install |
| `nerd-fonts-Symbols` (in your terminal's font list for the terminal app) | The file icons and git glyphs; or `glyphs = "ascii"` ([Glyphs and fonts](../customise/glyphs-and-fonts.md)) |
| `noto-ttf` | Japanese, Chinese and Korean letters in the desktop app |
| `tesseract` | Search the words in scans and pictures ([Scans and pictures](../search/scans.md)) |
| `poppler-utils` | The same for scanned PDFs |
| `libreoffice` | Search older Office files |
| `pandoc-cli` | Previews of formats it converts, in the desktop app |
| `ffmpeg7` | Videos and sound the player cannot play, video facts, [Convert video or audio](../files/convert-media.md); containers do not run here |
| `ImageMagick` | GIMP and RAW photos in the preview, [Convert or edit pictures](../files/edit-pictures.md) |
| `gdal` | Maps and facts of GeoPackage, shapefile, GeoJSON, KML and GeoTIFF files, [Convert geodata](../previews/geodata.md#convert-geodata) |
| `openscad` | Pictures of OpenSCAD models, [Export 3D model](../previews/openscad.md#export-3d-model) |
| `kicad` | KiCad schematics and boards in the preview, [Export from KiCad](../previews/kicad.md#export-from-kicad) |
| `git` | Git status, history and branches in the panels |
| `xdg-utils` | `xdg-open`, which opens a file in its program |

Where one of them is missing, the app names the `pkgin install` line. Coxswain never runs it.

## Starting the apps

| App | Start | Notes |
|---|---|---|
| Terminal app | `coxswain` or `cox`, optionally with two folders | Any terminal with 256 colours; `xterm` from the base system works. On the console (`wscons`), `glyphs = "ascii"`. `coxswain --help` lists the command-line flags |
| Desktop app | `coxswain-gui`, or *Coxswain* in the desktop's menu | An X11 session (the base system's X) |

## The search helper

By default the [search helper](../search/helper.md) starts with the first Coxswain app and
leaves ten minutes after the last. To have it read while no app is open:

### From boot, with rc.d

The script installs `/etc/rc.d/coxswain_index` (with the prefix `/usr/local`). It runs the helper
as the user you name, with that user's home; what it says goes to syslog
(`/var/log/messages`, tagged `coxswain_index`). In `/etc/rc.conf`:

```sh
coxswain_index=YES
coxswain_index_user=alice
```

then `/etc/rc.d/coxswain_index start` (as root), and `status` or `stop` the same way. Without a
user it refuses to start and says what to set. NetBSD has no daemon(8) to start the helper again
if it ends; it rarely does, and `/etc/rc.d/coxswain_index start` brings it back.

### With your desktop session, or your login shell

*Start with my session* in the terminal app's Settings (**F12** → *Finding files*), or `coxswain --index-service on`, writes
an XDG autostart entry (`~/.config/autostart/coxswain-index.desktop`) that a desktop session
reads. Without one, in `~/.profile`:

```sh
coxswain --index-helper --stay >/dev/null 2>&1 &
```

## How NetBSD differs from Linux here

| Feature | On NetBSD |
|---|---|
| File watching | kqueue, folders only. Each watched folder holds a file descriptor: the helper raises its limit to the hard one (`ulimit -Hn`, 3404 by default) and watches at most three quarters of it, about 2,500 folders, shallowest first. Folders past them are read again at the hourly rebuild |
| Trash (F8) | `~/.local/share/Trash`, the freedesktop.org layout |
| Battery | envstat(8): an `acpiacad` adapter with `connected: FALSE` means on battery, and the helper pauses ([Battery](../search/battery.md)) |
| Memory in the setup guide | `sysconf(_SC_PHYS_PAGES)` |
| Removable disks | Known by their path only ([Removable disks](../search/removable-disks.md)) |
| File flags | Not shown or set: Properties has no *Flags* line, and **F9** → *File flags* says *File flags are for FreeBSD and macOS* |
| ZFS | NetBSD's ZFS is not read; **Alt+Z** says the folder is not on ZFS |
| The update notice | Names the install line ([Updating](#updating-and-uninstalling)) |

## Updating and uninstalling

The update notice names the install line again, which replaces Coxswain where it is installed:

```sh
ftp -o - https://raw.githubusercontent.com/mwo-dk/coxswain/master/install/install-unix.sh | sh
ftp -o - https://raw.githubusercontent.com/mwo-dk/coxswain/master/install/install-unix.sh | sh -s -- --uninstall
```

Uninstalling removes the program, the manual page, the rc.d script and the autostart entry; take
the two lines out of `/etc/rc.conf` yourself. Your settings and the index stay:
`rm -rf ~/.config/coxswain ~/.local/share/coxswain ~/.cache/coxswain`.

## Building from source

```sh
pkgin install git rust
git clone https://github.com/mwo-dk/coxswain.git && cd coxswain
cargo build --release --locked -p coxswain
```

For the desktop app as well (Node.js for the frontend):

```sh
pkgin install nodejs webkit-gtk41 pkgconf
(cd gui && npm ci && npm run build)
cargo build --release --locked -p coxswain-gui
```

On another architecture that pkgsrc's Rust supports (aarch64 too) this is the way, as is
`cargo install --locked coxswain`. The build needs Rust 1.93 or later.

## The desktop app: what experimental means

The desktop app is a [Tauri](https://tauri.app) app, and Tauri does not support NetBSD
officially. It builds and runs because its window layer is GTK on the BSDs as on Linux, with the
same two patched crates as on [FreeBSD](freebsd.md#the-desktop-app-what-experimental-means).
NetBSD's `ld.so` looks only in `/usr/lib`, so the build writes pkgsrc's `/usr/pkg/lib` and the
base X's `/usr/X11R7/lib` into the program (an rpath), as pkgsrc's own packages do: no
`LD_LIBRARY_PATH` is needed.

Tested in CI on NetBSD 10.1 (amd64): it builds, its tests pass, and it starts under X11 and
draws its window. Browsing, the preview pane, Find and the file operations are the same code as
on FreeBSD and Linux, tested by the core's tests on NetBSD; they have not had use on a real
NetBSD desktop yet. Please say what works and what does not in an
[issue](https://github.com/mwo-dk/coxswain/issues).

## The pkgsrc package

A package for pkgsrc-wip, `wip/coxswain`, is ready in
[`packaging/pkgsrc`](../../packaging/pkgsrc/SUBMIT.md) but not yet submitted. It builds the
terminal app from the crates.io release and installs `coxswain`, `cox`, the manual page and the
rc.d script for the search helper (in `/usr/pkg/share/examples/rc.d`). CI builds it with
`make package` on NetBSD 10.1, installs it with `pkg_add` and runs it. The package holds the
terminal app only for now; the desktop app comes from the install script or the release's
`coxswain-desktop` archive.

## Questions

#### Why is it not in pkgsrc?

Not yet: the package is prepared ([above](#the-pkgsrc-package)) and
goes to pkgsrc-wip first. Until then, the script, the archives or `cargo install --locked coxswain`.

#### Why does the desktop app say it is experimental?

Tauri, which it is built on, does not support NetBSD officially. It is tested in CI as far as
starting and drawing its window ([above](#the-desktop-app-what-experimental-means)); the rest is
the same code as on FreeBSD and Linux, with little use on NetBSD desktops yet.

#### The desktop app's window stays empty or it does not start

`webkit-gtk41` must be installed (`pkgin install webkit-gtk41`). On a machine without working
3D drivers, start it with `WEBKIT_DISABLE_COMPOSITING_MODE=1 coxswain-gui`, as CI does under
Xvfb.

#### Does it run on NetBSD 9?

It is built and tested on 10.1 only. On 9, build from
source if pkgsrc's Rust there is 1.93 or later.

#### Why does the helper miss new files deep in my tree for a while?

Their folders are past the
2,500 or so it can watch ([above](#how-netbsd-differs-from-linux-here)). A higher
`kern.maxfiles` and hard limit help (`ulimit -Hn` is set by the login class in
`/etc/login.conf`), as does leaving large trees out of the index (`name_exclude` in `[search]`).

#### The battery is not noticed

envstat must list an `acpiacad` adapter: `envstat -d acpiacad0`.
Machines without one count as on mains.

---
[← Previous: FreeBSD](freebsd.md) · [Next: OpenBSD →](openbsd.md)