From dc059db6db67abad249fa153593a89a45fa37486 Mon Sep 17 00:00:00 2001 From: srdusr <99972264+srdusr@users.noreply.github.com> Date: Mon, 25 May 2026 23:13:00 +0200 Subject: Version flag, Makefile, and honest cross-platform documentation Neither binary had a -version flag - a basic expectation for any CLI tool, and useful for anyone reporting a bug ("which build is this"). internal/version holds Version/Commit/Date, set via -ldflags "-X mitmux/internal/version.X=..." at build time and defaulting to "dev" for a plain `go build` with no ldflags, so -version is never blank or misleading about whether a given binary is a tagged release or a local build. Both mitmux and mitmuxd gained a -version flag that prints it and exits. Makefile: `make build` (both binaries for the current platform, version info from `git describe`), `make test` (the same build/vet/gofmt/test checks expected before every commit here), `make install` (a thin wrapper over `go install`, respecting GOBIN/GOPATH as usual - not reimplementing Go's own path resolution), `make release` (cross-compiles both binaries for linux/darwin/windows/freebsd, amd64+arm64 where it makes sense, into dist/). Every target is CGO_ENABLED=0: modernc.org/sqlite is pure Go, so no C toolchain is needed anywhere, cross-compiling included - this was already true before this commit, just not verified or made easy to use. Verified live, every target actually run rather than just written: `make build` produces working binaries with version info correctly picked up from git (confirmed against a real -version invocation, both the "dev" default and an ldflags-injected release-style version string); `make test` runs clean; `make release` was run for real and produced 6 platform/arch binaries, each confirmed with `file` to be a genuinely correctly-formatted executable for its target (Mach-O for both macOS architectures, PE32+ for Windows, ELF for both Linux architectures and FreeBSD) - not just "the command exited zero." `make install`'s correctness rests on `go install` itself, Go's own well-tested mechanism; deliberately not run for real here since it writes into the real GOPATH/bin outside this repo, unprompted. README gained an honest Platforms section: Linux is what's actually been run and verified throughout this project's development; macOS, Windows, and FreeBSD cross-compile cleanly and pass go vet, and the code has nothing Linux-specific in it (CA/history storage already used Go's own cross-platform os.UserConfigDir, not a hardcoded XDG path - also fixed the README's install-directory example, which had been Linux-only text), but they haven't run on real hardware, so they're documented as "should work, not yet verified" rather than a claim this session can't actually back up. Also flagged a concrete, real gotcha: macOS's shorter Unix domain socket path limit combined with the deeper ~/Library/Application Support default control-socket location could matter for a long username, with the existing -socket flag as the workaround. go build/vet/gofmt/test/mod tidy all clean. --- README.md | 47 +++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 4 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 4a9def0..7173984 100644 --- a/README.md +++ b/README.md @@ -69,20 +69,57 @@ list of what's deliberately not implemented (and why), see ## Install / build -Requires Go 1.26.5+ (see `go.mod`). +Requires Go 1.26.5+ (see `go.mod`). No other dependencies - the SQLite +driver ([modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite)) is +pure Go, so there's no C toolchain to install and nothing to link +against, on any platform. ```sh git clone cd mitmux +make build # -> bin/mitmuxd, bin/mitmux +``` + +`make build` covers the common case; see the [`Makefile`](Makefile) +itself for the rest - `make install` (via `go install`, respecting +`GOBIN`/`GOPATH` as usual), `make release` (cross-compiles both +binaries for every platform in `PLATFORMS` into `dist/`), `make test` +(the same build/vet/gofmt/test checks expected before every commit - +see `PLAN.md`). Building without `make` works identically: + +```sh go build -o bin/mitmuxd ./cmd/mitmuxd go build -o bin/mitmux ./cmd/mitmux ``` +### Platforms + +Linux is the primary target and the only one this has actually run on +during development - every feature in this document was verified live +against a real daemon and real traffic there. macOS, Windows, and +FreeBSD all cross-compile cleanly with `CGO_ENABLED=0` and pass `go +vet` (`make release` builds all of them), and the code itself has +nothing Linux-specific in it - CA/history storage uses Go's own +cross-platform `os.UserConfigDir()`, not a hardcoded XDG path - but +they haven't been run on real hardware, so treat them as "should work, +not yet verified" rather than a tested claim. If you try one and hit +something, that's useful to know about. + +One concrete thing worth knowing on macOS specifically: its Unix +domain socket path limit is shorter than Linux's, and the default +control-socket location lives under `~/Library/Application +Support/mitmux/` - a deeper path than Linux's usual +`$XDG_RUNTIME_DIR`. A long username or home directory path could push +past the limit; if `mitmuxd` fails to bind its control socket, pass a +shorter `-socket /tmp/mitmux.sock` (and the matching `-socket` to +`mitmux`) to both binaries. + ## Quick start 1. **Start the daemon.** By default it listens on `127.0.0.1:8080` and - stores its CA and history database under `~/.config/mitmux` (XDG - config dir): + stores its CA and history database under your OS's standard config + directory (Linux: `~/.config/mitmux`, macOS: `~/Library/Application + Support/mitmux`, Windows: `%AppData%\mitmux`): ```sh ./bin/mitmuxd @@ -124,7 +161,9 @@ go build -o bin/mitmux ./cmd/mitmux Both binaries take flags for non-default setups - `-listen`, `-socket`, `-ca-dir`, `-db`, `-upstream-proxy` on `mitmuxd`; `-socket` on `mitmux`. -Run either with `-h` for the full list. +Both also take `-version` (prints version/commit/date and exits - `dev` +for a plain `go build`; `make build`/`make release` fill it in from +`git describe`) and `-h` for the full list. `-listen` takes a comma-separated list to bind more than one address (`-listen "127.0.0.1:8080,127.0.0.1:8081"`) - one logical proxy on -- cgit v1.2.3