Split install instructions into separate pages (#60)

* Split install instructions into separate pages

Also list "static bins" options where available,
and clean up some wording.

* Touch up wording of OS list

Co-authored-by: Rangi <[email protected]>

* Fix typo

Co-authored-by: Rangi <[email protected]>

* Improve wording of Linux page

Co-authored-by: Rangi <[email protected]>

* Integrate Sylvie's improvements

Co-authored-by: Sylvie <[email protected]>

* Add link back to "main" install page to sub-pages

* Fix up install instructions more

* Make the breakage disclaimer of `master` less scary

The update pace has slowed down a lot anyway

* Clean up documentation related to `master`

* Prefer following links instead of clicking them

* Simplify directions to install downloads

* Use headings for different installation methods

This delineates them much better, and also allows linking to
individual methods much more easily!

* Clarify availability of Homebrew install method

* Make install docs into a separate "doc instance"

Notably, this enables a sidebar, and automatic breadcrumbs.

* Use markdown links in install instructions

These are more stable, and converted+checked at compile time

* Update install/linux.md

Co-authored-by: Sylvie <[email protected]>

* Update install/macos.md

Co-authored-by: Sylvie <[email protected]>

* Update install/source.md

Co-authored-by: Sylvie <[email protected]>

* Update install/windows.md

Co-authored-by: Sylvie <[email protected]>

* Recommend the use of WSL

Co-authored-by: Sylvie <[email protected]>

* final touches

* macos: add note about homebrew on old OS

---------

Co-authored-by: Rangi <[email protected]>
Co-authored-by: Antonio Vivace <[email protected]>

docs/index.md

@@ -3,7 +3,8 @@
 
 ## What is `master`? {#master}
 
-`master` is the name of RGBDS' main development branch. It's usually employed as a version name to refer to the state of in-development RGBDS: it contains the latest changes as they are pushed, but for this reason it's very unstable.
+`master` is the name of RGBDS' main development branch.
+It's used to refer to "bleeding-edge" RGBDS, containing the latest changes as they are pushed.
 
 ### Pros and cons of `master` over releases
 
@@ -15,7 +16,7 @@ Pros:
 
 Cons:
 
-- Tested, but unstable, so expect things to break often
+- Tested, but less stable, so expect things to break occasionally
 - Must be compiled manually, unless you [use our CI](/install/master#using-our-ci)
 - Updated often
 

docusaurus.config.js

@@ -33,31 +33,9 @@ const config = {
  organizationName: "gbdev",
  projectName: "rgbds-www",
 
- plugins: [
- [
- "@docusaurus/plugin-client-redirects",
- {
- redirects: [
- "gbz80.7",
- "rgbasm.1",
- "rgbasm.5",
- "rgbds.5",
- "rgbds.7",
- "rgbfix.1",
- "rgbgfx.1",
- "rgblink.1",
- "rgblink.5",
- ].map((page) => {
- return { from: `/docs/${page}`, to: `/docs/${latestStable}/${page}` };
- }),
- },
- ],
- "docusaurus-plugin-matomo",
- ],
-
  presets: [
  [
- "classic",
+ "@docusaurus/preset-classic",
  /** @type {import('@docusaurus/preset-classic').Options} */
  {
  docs: {
@@ -81,6 +59,37 @@ const config = {
  ],
  ],
 
+ plugins: [
+ [
+ "@docusaurus/plugin-content-docs",
+ {
+ id: "install",
+ path: "install",
+ routeBasePath: "install",
+ sidebarPath: "./installSidebars.js",
+ }
+ ],
+ [
+ "@docusaurus/plugin-client-redirects",
+ {
+ redirects: [
+ "gbz80.7",
+ "rgbasm.1",
+ "rgbasm.5",
+ "rgbds.5",
+ "rgbds.7",
+ "rgbfix.1",
+ "rgbgfx.1",
+ "rgblink.1",
+ "rgblink.5",
+ ].map((page) => {
+ return { from: `/docs/${page}`, to: `/docs/${latestStable}/${page}` };
+ }),
+ },
+ ],
+ "docusaurus-plugin-matomo",
+ ],
+
  themeConfig:
  /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
  ({

install/index.md

@@ -0,0 +1,31 @@
+---
+sidebar_label: Available install methods
+---
+
+# Installing RGBDS
+
+Most people will want to use a stable release (the more recent the better).
+
+These are the operating systems for which pre-built executables of recent releases of RGBDS are available:
+- [Linux](linux.md)
+- [macOS](macos.md)
+- [Windows](windows.md)
+
+If none of these options fit your needs, you can [build from source](source.md).
+
+### Docker
+
+We distribute an [official container image for RGBDS](https://github.com/gbdev/rgbds/pkgs/container/rgbds).
+It contains the built executables *and* the build dependencies, in case you want to compile from source.
+
+```bash
+docker pull ghcr.io/gbdev/rgbds:latest
+```
+
+### Installing a development version
+
+If you are willing to help us test new features, consider [using a development version](master.md).
+
+### Managing multiple versions
+
+If you need to frequently switch between different versions of RGBDS, consider using [rgbenv](https://github.com/gbdev/rgbenv), the RGBDS version manager.

install/linux.md

@@ -0,0 +1,28 @@
+---
+sidebar_label: Linux
+---
+
+# Installing RGBDS on Linux
+
+## Using your package manager
+
+Check if RGBDS is available in your distribution's software center or package manager repositories.
+If a satisfactory version is available, it is a good idea to install from there.
+
+## Using our pre-built binaries
+
+1. Go the [latest release](https://github.com/gbdev/rgbds/releases/latest) (or pick [a specific version](https://github.com/gbdev/rgbds/releases))
+2. Under "Assets" at the bottom, download <code>rgbds-<var>&lt;version&gt;</var>-linux-x86_64.tar.xz</code> (for example, version 0.7.0 would have `rgbds-0.7.0-linux-x86_64.tar.xz`)
+3. Extract the .tar.xz file into a new directory, and run `install.sh` as root in that directory. E.g.:
+ ```console
+ % mkdir rgbds
+ % tar xf rgbds-0.7.0-linux-x86_64.tar.xz -C rgbds
+ % cd rgbds
+ % sudo ./install.sh
+ ```
+4. Check that RGBDS was correctly installed by running `rgbasm -V`.
+ It should print out the version number you installed!
+
+---
+
+If none of these options are suitable to you, [build RGBDS from source](source.md).

install/macos.md

@@ -0,0 +1,40 @@
+---
+sidebar_label: macOS
+---
+
+# Installing RGBDS on macOS
+
+## Using the Homebrew package manager
+
+On recent macOS major releases[^1], RGBDS is available on [Homebrew](https://brew.sh) as the [`rgbds` package](https://formulae.brew.sh/formula/rgbds).
+
+```bash
+brew install rgbds
+```
+
+Then you will be able to update RGBDS at any time by simply running `brew update` then `brew upgrade`!
+
+You can also install the [`master` branch](/docs/master) by passing the `--HEAD` flag:
+```bash
+brew install rgbds --HEAD
+```
+
+## Using our pre-built binaries
+
+1. Go the [latest release](https://github.com/gbdev/rgbds/releases/latest) (or pick [a specific version](https://github.com/gbdev/rgbds/releases))
+2. Under "Assets" at the bottom, download <code>rgbds-<var>&lt;version&gt;</var>-macos-x86-64.zip</code> (for example, version 0.7.0 would have `rgbds-0.7.0-macos-x86-64.zip`).
+3. Extract the .zip file into a new directory, and run `install.sh` as root inside that directory.
+ For example, you can do that with these Console commands:
+ ```console
+ % unzip -d rgbds rgbds-0.7.0-macos-x86-64.zip
+ % cd rgbds
+ % sudo ./install.sh
+ ```
+4. Check that RGBDS was correctly installed by running `rgbasm -V`.
+ It should print out the version number you installed!
+
+---
+
+If none of these options are suitable to you, [build RGBDS from source](source.md).
+
+[^1]: Older macOS systems have been reported to compile for several days with Homebrew.

src/pages/install/master.md → install/master.md

@@ -1,30 +1,22 @@
+---
+sidebar_label: Using a development version
+---
 
 # Using RGBDS `master`
 
 `master` is the name of RGBDS' main development branch.
 Using a "master" version of RGBDS means using an in-development version: this means you get access to the newest features faster (and you help test them!), but it also means that they have undergone a little less testing.
 
 We are very grateful to all who takes the time to use `master` versions; all of you help make the releases better for everyone.
-But, if you don't want to, you can [go back to the install page](/install).
 
 ## Using a package manager
 
-Your package manager *may* have a `master` version of RGBDS available, such as Arch's [`rgbds-git` AUR package](https://aur.archlinux.org/packages/rgbds-git).
+Your package manager *may* have a `master` version of RGBDS available, such as Arch Linux [`rgbds-git` AUR package](https://aur.archlinux.org/packages/rgbds-git).
 If that is the case, it is recommended to use that, as it should be simpler and integrate better with the rest of your system.
 
-As this is highly OS-specific, we cannot provide any generic instructions.
-Sorry!
-
 ## Building it yourself
 
-:::tip
-
-If your package manager is not an option, this is the preferred way.
-Unless you are on Windows, in which case consider [using our CI](#using-our-ci) instead.
-
-:::
-
-[Build the source](/install/source) as usual, but replace step 1 (getting the sources) with getting the `master` repo instead.
+[Build the source](source.md) as usual, but replace step 1 (getting the sources) with getting the `master` repo instead.
 The recommended way is to clone the repo (see [GitHub's help on it](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) if you have trouble), but you can also download the repo as ZIP.
 
 Then, follow the rest of the instructions to build from source.

src/pages/install/source.md → install/source.md

@@ -1,3 +1,6 @@
+---
+sidebar_label: Building RGBDS yourself
+---
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -24,11 +27,9 @@ You first need to get the source files to be compiled, using one of the methods
 <Tabs>
 <TabItem value="snapshot" label="Downloading source snapshots">
 
-1. [Pick a release](/docs).
-2. Under the "GitHub links" heading, follow the `release page` link.
-3. Go to "**Assets**" at the bottom of that page.
-4. Download any of the last three listed files (`rgbds-<version>.tar.gz`, "Source code (`zip`)", or "Source code (`tar.gz`)").
-5. Extract ("unzip") the file.
+1. Go the [latest release](https://github.com/gbdev/rgbds/releases/latest) (or pick [a specific version](https://github.com/gbdev/rgbds/releases))
+2. Under "Assets" at the bottom, download any of the last three listed files (<code>rgbds-<var>&lt;version&gt;</var>.tar.gz</code>, "Source code (`zip`)", or "Source code (`tar.gz`)").
+3. Extract ("unzip") the file.
 
 </TabItem>
 <TabItem value="git" label="Using Git">

install/windows.md

@@ -0,0 +1,101 @@
+---
+sidebar_label: Windows
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Installing RGBDS on Windows
+
+The install instructions are a bit different depending on the environment in which you wish to use RGBDS.
+
+<Tabs>
+<TabItem value="wsl" label="WSL">
+
+Using WSL is recommended if your version of Windows supports it (which Windows 10 and 11 do).
+
+Please refer to [the install instructions](linux.md) for your WSL's running Linux distribution.
+You can check what your WSL distribution is by running `wsl -l -v` in the Command Prompt.
+(The default Linux distribution on WSL is Ubuntu, whose package manager is `apt`.)
+
+</TabItem>
+<TabItem value="cygwin" label="Cygwin / MSYS2">
+
+1. Go the [latest release](https://github.com/gbdev/rgbds/releases/latest) (or pick a specific version from [the list](https://github.com/gbdev/rgbds/releases)).
+2. Under "Assets" at the bottom, download either <code>rgbds-<var>&lt;version&gt;</var>-win32.zip</code> (for 32-bit Windows) or <code>rgbds-<var>&lt;version&gt;</var>-win64.zip</code> (for 64-bit Windows).
+ (For example, version 0.7.0 for 64-bit Windows would have `rgbds-0.7.0-win64.zip`).
+3. Unzip the .zip file.
+ It should give you the RGBDS `.exe` files and a couple of `.dll` files.
+4. Copy all of those `.exe` and `.dll` files to the `/usr/local/bin` directory of your Cygwin/MSYS2 installation.
+ (You can learn its equivalent Windows path by running `cygpath -w /usr/local/bin` in the Cygwin terminal.)
+
+ :::caution
+
+ Do not put them in a subdirectory (e.g. `/usr/local/bin/rgbds/`)!
+ This would not work.
+
+ :::
+
+After that, you should be able to use RGBDS from within the Cygwin/MSYS2 terminal, which you can confirm by running `rgbasm -V`.
+
+If `rgbasm -V` doesn't work, check that `/usr/local/bin` is listed in your Cygwin/MSYS2 `PATH` (run `echo $PATH` to check).
+If it isn't listed, you must add it (e.g. run `echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc`, then close your Cygwin terminal and open a new one).
+
+:::tip
+
+If you can choose between using Cygwin or MSYS2, be advised that Cygwin is slower and has been reported to cause a bit of trouble to some.
+
+:::
+
+</TabItem>
+<TabItem value="win32" label="None of those">
+
+1. Go the [latest release](https://github.com/gbdev/rgbds/releases/latest) (or pick a specific version from [the list](https://github.com/gbdev/rgbds/releases))
+2. Under "Assets" at the bottom, download either <code>rgbds-<var>&lt;version&gt;</var>-win32.zip</code> (for 32-bit Windows) or <code>rgbds-<var>&lt;version&gt;</var>-win64.zip</code> (for 64-bit Windows).
+ (For example, version 0.7.0 for 64-bit Windows would have `rgbds-0.7.0-win64.zip`).
+3. Unzip the .zip file.
+ It should give you the RGBDS `.exe` files and a couple of `.dll` files.
+4. Either:
+ - ...put all of the files in a directory, then add that directory to Windows' `PATH`.
+ This will *permanently* allow you to use RGBDS *from any directory*.
+
+ <Tabs>
+ <TabItem value="gui" label="Graphically">
+
+ 1. Open the Environment Variables dialog for your account.
+ You can do this by either:
+ - ...typing "edit environment variables for your account" in the Start menu's Search box and clicking the Control Panel item that's found.
+ - ...opening the Control Panel, clicking its "User Accounts" item, clicking the "User Accounts" heading in that item, and clicking "Change my environment variables" in the sidebar.
+ 2. Click the "Path" line in the **top** panel to highlight it.
+ 6. Click "Edit..." to open the "Edit environment variable" dialog for "Path".
+ 7. Click "Browse...", select the folder that the RGBDS files are in, and click OK.
+ 8. The folder should be added to the bottom of the "Path" list.
+ Make sure that the new entry (which should be highlighted) is at the bottom of the list; if not, click on "Move Down" until it is.
+ 9. Click "OK" to finish the "Edit environment variable" dialog, and again for the "Environment Variables" dialog.
+
+ </TabItem>
+ <TabItem value="cmd" label="Command Prompt">
+
+ Run the command <code>setx PATH "%PATH%<var>&lt;rgbds_path&gt;</var>;"</code>, replacing <code><var>&lt;rgbds_path&gt;</var></code> with the path to the directory that contains `rgbasm.exe`, `rgblink.exe`, etc.
+ Then close the Command Prompt and open a new one for the changes to take effect.
+
+ If you only want to modify the `PATH` temporarily, instead of the permanent [`setx`](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx) command, you can use the **temporary** [`set`](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1).
+
+ </TabItem>
+ <TabItem value="pwsh" label="PowerShell">
+
+ Run the command <code>setx PATH \$\{Env:PATH\}<var>&lt;rgbds_path&gt;</var>;</code>, replacing <code><var>&lt;rgbds_path&gt;</var></code> with the path to the directory that contains `rgbasm.exe`, `rgblink.exe`, etc.
+ Then close the PowerShell window and open a new one for the changes to take effect.
+
+ If you only want to modify the `PATH` temporarily, instead of the permanent [`setx`](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/setx) command, you can use the **temporary** [`set`](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1).
+
+ </TabItem>
+ </Tabs>
+
+ - ...or put all of the files in your project's directory.
+ - ...or put all of the files in a directory already in the `PATH`.
+5. RGBDS can now be used from your favorite command line (most likely the Command prompt or PowerShell).
+ You can test it by running `rgbasm -V`, which should print the version you installed!
+
+</TabItem>
+</Tabs>

installSidebars.js

@@ -0,0 +1,22 @@
+// @ts-check
+
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebars = {
+ nav: [
+ "index",
+ {
+ type: "category",
+ label: "Supported OSes",
+ collapsible: false,
+ items: [
+ "linux",
+ "macos",
+ "windows",
+ ],
+ },
+ "source",
+ "master",
+ ],
+};
+
+module.exports = sidebars;