Correct the install docs: prerequisites, commands, and repo links - #39
Merged
Conversation
The install pages had a cluster of errors that each cost a new user time. Prerequisites were wrong. Both pages said a prebuilt install needs no Rust or LLVM, but the compiler calls clang to link every program it builds, so clang matching the linked LLVM major is required to run anything at all. Say so, give the per-platform command, and point at `mux doctor`, which the installers now run automatically. Commands were wrong. `mux --version` does not exist - clap rejects it, and the real `--help` has no version flag - so the documented way to verify an install fails. The correct form is `mux version`. The pasted help output also listed a `try` command that is not in the CLI. Source-build instructions were wrong. They cloned mux-compiler and then `cd mux-lang`, and pointed at `target/release/mux-compiler` for a binary that is called `mux` and, under dev-cargo.sh, lands in `target/dev-cargo/`. All 16 repo links pointed at derekcorniello/mux-lang, the pre-split path. Those still resolve through a GitHub rename redirect, but AGENTS.md says user-facing links target muxlang/mux-compiler, and a redirect is not something to rely on. The GitHub Discussions link was a genuine 404 - discussions are disabled on the repo - so it now points at Issues. Mark the crates.io section frozen. It is the slowest path to a working compiler (Rust plus exact LLVM 22 dev libraries, then a full llvm-sys build) and it is no longer updated.
Cargo emits a dependency's rlib and never its staticlib, so `dev-cargo.sh build` alone leaves no libmux_runtime.a and every compiled program fails to link. Both source-build paths said to run exactly that. Build both packages in the Setup and Quick Start instructions, and say why. Option 4 needed more: `cargo install` copies only the binary, so the archive has to be placed where the compiler looks - `~/.cargo/lib/`, beside `~/.cargo/bin/mux` - or named by MUX_RUNTIME_LIB.
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Contributor
|
| Filename | Overview |
|---|---|
| docs/getting-started/quick-start.md | Updates prerequisites, installer links, verification commands, source-build steps, runtime archive installation, and CLI help output; the added directory creation resolves the previous installation failure. |
| docs/setup.md | Clarifies prebuilt and source-build dependencies and corrects the build and verification commands. |
| docs/design-notes/philosophy.md | Replaces the unavailable Discussions destination with the compiler repository’s Issues page. |
| docs/index.md | Updates community and contribution links to the current compiler repository. |
Reviews (2): Last reviewed commit: "Create ~/.cargo/lib before copying the r..." | Re-trigger Greptile
Cargo does not create that directory, so on a fresh installation the copy in Option 4 failed with "No such file or directory" and left the compiler unable to link programs - the exact failure the instructions were added to prevent. Caught in review on #39.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation only. Most of this is independent of the runtime work and could merge on its own.
Prerequisites were wrong
Both pages said a prebuilt install needs no Rust or LLVM. The compiler calls clang to link every program it builds, so clang matching the linked LLVM major is required to run anything at all - not just to build from source. Now stated, with the per-platform command, plus a pointer to
mux doctor, which the installers now run automatically (muxlang/mux-compiler#317).Commands were wrong
mux --versiondoes not exist - clap rejects it, and the real--helphas no version flag - so the documented way to verify an install fails outright. The correct form ismux version. The pasted help output also listed atrycommand that is not in the CLI.Source-build instructions were wrong
They cloned
mux-compilerand thencd mux-lang, and pointed attarget/release/mux-compilerfor a binary calledmuxthat lands intarget/dev-cargo/under the dev wrapper.They also said to run
dev-cargo.sh build, which produces a compiler that cannot link anything: cargo emits a dependency's rlib and never its staticlib, solibmux_runtime.ais never built. Now-p mux-runtime -p mux-lang, with the reason. Option 4 (cargo install --path) needed more - it copies only the binary, so the archive has to be placed at~/.cargo/lib/where the compiler looks.Links
All 16 repo links pointed at
derekcorniello/mux-lang, the pre-split path. Those still resolve through a GitHub rename redirect, butAGENTS.mdsays user-facing links targetmuxlang/mux-compiler, and a redirect is not something to depend on. The GitHub Discussions link was a genuine 404 - Discussions are disabled on the repo - so it now points at Issues.crates.io
Marked frozen per muxlang/mux-context#32. It is the slowest path to a working compiler (Rust plus exact LLVM 22 dev libraries, then a full llvm-sys build) and is no longer updated.
Verification
npm run typecheck,npm run lint, andnpm run buildall pass. No ```mux fences were added or altered, socheck:docs-snippetsshould be unaffected.Need help on this PR? Tag
@codesmith-botwith what you need. Autofix is disabled.