srdusr
aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
authorsrdusr <[email protected]>2026-05-25 23:13:00 +0200
committersrdusr <[email protected]>2026-05-25 23:13:00 +0200
commitdc059db6db67abad249fa153593a89a45fa37486 (patch)
tree2b30974599b66975906c3dc8c1a3258418147648 /README.md
parent0d1ce88962fe31ce1d204634e6ea10998a02827a (diff)
downloadmitmux-dc059db6db67abad249fa153593a89a45fa37486.tar.gz
mitmux-dc059db6db67abad249fa153593a89a45fa37486.zip
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.
Diffstat (limited to 'README.md')
-rw-r--r--README.md47
1 files changed, 43 insertions, 4 deletions
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 <this repo>
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