From fac3bf59c1158160e74fade4f635bde0d5cb771a Mon Sep 17 00:00:00 2001 From: Matt Godbolt Date: Sun, 11 May 2025 16:46:05 -0500 Subject: [PATCH] Documentation improvements (#7672) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR includes various documentation improvements: - Fix grammar in README.md introduction - Update Node.js version references to consistently indicate 'Node.js 20 or higher' - Enhance macOS installation and setup guide with detailed instructions - Fix broken link in API.md - Fix formatting inconsistencies in WhatIsCompilerExplorer.md 🤖 Generated with [Claude Code](https://claude.ai/code) --------- Co-authored-by: Claude --- README.md | 6 +++--- docs/API.md | 4 ++-- docs/RunningOnMacOS.md | 20 ++++++++++++++++++-- docs/WhatIsCompilerExplorer.md | 4 ++-- 4 files changed, 25 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index dcfd5ef99..95812c5e2 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,9 @@ # Compiler Explorer -Is an interactive compiler exploration website. Edit code in C, C++, C#, F#, Rust, Go, D, Haskell, Swift, Pascal, +Compiler Explorer is an interactive compiler exploration website. Edit code in C, C++, C#, F#, Rust, Go, D, Haskell, Swift, Pascal, [ispc](https://ispc.github.io/), Python, Java, or any of the other -[30+ supported languages](https://godbolt.org/api/languages) components, and see how that code looks after being +[30+ supported languages](https://godbolt.org/api/languages), and see how that code looks after being compiled in real time. [Bug Report](https://github.com/compiler-explorer/compiler-explorer/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBUG%5D%3A+) @@ -75,7 +75,7 @@ Assuming you have a compatible version of `node` installed, on Linux simply runn running with an Explorer running on port 10240 on your local machine: [http://localhost:10240/](http://localhost:10240/). If this doesn't work for you, please contact us, as we consider it important you can quickly and easily get running. Currently, **Compiler Explorer** requires -[`node` 22](CONTRIBUTING.md#node-version) installed, either on the path or at `NODE_DIR` (an environment variable or +[`node` 20 or higher](CONTRIBUTING.md#node-version) installed, either on the path or at `NODE_DIR` (an environment variable or `make` parameter). Running with `make EXTRA_ARGS='--language LANG'` will allow you to load `LANG` exclusively, where `LANG` is one for the diff --git a/docs/API.md b/docs/API.md index ab1a4ac81..3c8719bc3 100644 --- a/docs/API.md +++ b/docs/API.md @@ -183,8 +183,8 @@ structure: ``` The name property corresponds to the `` when requesting `POST /api/format/`. The `type` key in the -JSON request corresponds to one of the `formatters..type` found in -[compiler-explorer.amazon.properties:43](../etc/config/compiler-explorer.amazon.properties#L43) +JSON request corresponds to one of the `formatters..type` found in the compiler-explorer configuration properties +(see [Configuration.md](Configuration.md) for more details) ### `POST /api/format/` - perform a formatter run diff --git a/docs/RunningOnMacOS.md b/docs/RunningOnMacOS.md index 061170d40..c1eb7426d 100644 --- a/docs/RunningOnMacOS.md +++ b/docs/RunningOnMacOS.md @@ -1,6 +1,22 @@ # Running on MacOS -## With default XCode installation +## Prerequisites + +1. **Node.js**: Ensure you have Node.js 20 or higher installed + - Installation options include Homebrew or the official installer from [nodejs.org](https://nodejs.org/) + +2. **Xcode Command Line Tools**: + - Required for compilers and build tools + - Can be installed via `xcode-select --install` + - Be sure to accept the Xcode EULA + +## Required Configuration Changes -* Be sure to have accepted the XCode EULA * Change in `etc/config/compiler-explorer.defaults.properties` the line `objdumperType=default` to `objdumperType=llvm` +* This ensures compatibility with macOS's LLVM-based toolchain + +## Notes + +* By default, Apple Clang will be available as a compiler +* For configuration details, see [Configuration.md](Configuration.md) +* Follow the standard setup instructions in the main [README.md](../README.md) diff --git a/docs/WhatIsCompilerExplorer.md b/docs/WhatIsCompilerExplorer.md index d1ab695d9..cf84d7c74 100644 --- a/docs/WhatIsCompilerExplorer.md +++ b/docs/WhatIsCompilerExplorer.md @@ -16,7 +16,7 @@ and `esi`, and result left in `eax`: 01fe89f0c3 ``` -Machine code may be what the computer needs, it is not a convenient representation for humans. Instead, _assembly_ is +Machine code may be what the computer needs, but it is not a convenient representation for humans. Instead, _assembly_ is commonly used, a (somewhat readable) text representation of the machine code. The encoding is bidirectional: humans can write assembly and have it encoded as machine code with a program called an _assembler_, and machine code can be turned into assembly with a _disassembler_. @@ -39,7 +39,7 @@ int add(int x, int y) { ``` A compiler turns this source into machine code (for example, GCC). The compiler parses and understands the C language, -turning the programmer's intention into the nitty-gritties of the target CPU's machine code. Compilers can also also +turning the programmer's intention into the nitty-gritties of the target CPU's machine code. Compilers can also perform _optimizations_ which can significantly improve the code performance over a naive transliteration. For example, passing GCC the C source above and asking it to optimize produces the following machine code/assembly: