diff options
| author | srdusr <[email protected]> | 2026-05-25 23:13:00 +0200 |
|---|---|---|
| committer | srdusr <[email protected]> | 2026-05-25 23:13:00 +0200 |
| commit | dc059db6db67abad249fa153593a89a45fa37486 (patch) | |
| tree | 2b30974599b66975906c3dc8c1a3258418147648 /README.md | |
| parent | 0d1ce88962fe31ce1d204634e6ea10998a02827a (diff) | |
| download | mitmux-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.md | 47 |
1 files changed, 43 insertions, 4 deletions
@@ -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 |