Revamp installation/setup guide based on https://github.com/gnustep/d…

…ocumentation

source/Guides/Setup/Linux/building-linux.md

@@ -0,0 +1,131 @@
+# Building on Linux
+
+We first need to install some prequisits including
+clang for Objective-C 2.0 support, and set some
+enviroment variables.
+
+Debian-based:
+```sh
+sudo apt install clang lld git cmake make pkg-config
+```
+
+Environment:
+```sh
+export CC=/usr/bin/clang
+export CXX=/usr/bin/clang++
+export PATH=/usr/local/bin:$PATH
+export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
+export LD=/usr/bin/ld.lld
+export LDFLAGS=-fuse-ld=/usr/bin/ld.lld
+```
+
+## 1.1 libobjc2
+
+We can now build and install the Objective-C runtime libobjc2.
+```sh
+git clone --recurse-submodules --branch <REPLACE_WITH_LATEST_TAG> "https://github.com/gnustep/libobjc2"
+cd libobjc2
+mkdir build && cd build
+cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo
+sudo make install
+```
+
+## 1.2 libdispatch
+
+Grand Central Dispatch (GCD) is a library that provides a
+low-level and efficient API for managing work across threads.
+
+```sh
+git clone --branch <REPLACE_WITH_LATEST_TAG> https://github.com/apple/swift-corelibs-libdispatch
+cd swift-corelibs-libdispatch/
+mkdir build && cd build
+cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo -DINSTALL_PRIVATE_HEADERS=YES
+sudo make install
+```
+
+## 1.3 GNUstep Make
+
+GNUstep make is a collection of makefiles and scripts to
+build GNUstep frameworks, libraries and applications.
+
+```sh
+git clone --branch <REPLACE_WITH_LATEST_TAG> https://github.com/gnustep/tools-make
+cd tools-make
+./configure \
+           --with-layout=fhs \
+           --enable-native-objc-exceptions \
+           --enable-objc-arc \
+           --enable-install-ld-so-conf \
+           --enable-debug-by-default
+sudo make install
+```
+
+## 1.4 GNUstep Base
+
+GNUstep Base features the Foundation framework, a collection of non-graphical Objective-C objects.
+Different from the Foundation framework on macOS, GNUstep Base is not based on CoreFoundation.
+You can still use CoreFoundation (a.k.a CoreBase) on GNUstep, but it is not required.
+
+### 1.4.1 Dependencies
+You will need to install the following dependencies before building GNUstep Base:
+- GNUstep Make (see above)
+- gnutls or openssl
+- libffi
+- libxml2
+- libxslt
+- zlib
+- libavahi
+- libicu
+- tzdata
+- libcurl
+
+Debian-based:
+```sh
+sudo apt install gnutls-bin, libffi-dev, libxml2-dev, libxslt1-dev, libgnutls28-dev, zlib1g-dev, libavahi-client-dev, libicu-dev, tzdata, libcurl4-openssl-dev
+```
+
+### 1.4.2 Building
+
+```sh
+# Source the GNUstep environment
+source /usr/local/share/GNUstep/Makefiles/GNUstep.sh
+
+# Clone the repository
+git clone --branch <REPLACE_WITH_LATEST_TAG> https://github.com/gnustep/libs-base
+
+cd libs-base
+./configure
+```
+
+## 1.5 GNUstep CoreBase
+If you are interested in using the C-based CoreFoundation
+API you can build and install GNUstep CoreBase.
+
+Please note that CoreBase is not that mature yet and you can run into
+issues when using it. For more information about the current state
+of CoreBase please see [TODO]().
+
+### 1.5.1 Dependencies
+- GNUstep Make (see above)
+- GNUstep Base (see above)
+- libicu
+
+Debian-based:
+```sh
+sudo apt install libicu-dev
+```
+
+### 1.5.2 Building
+
+```sh
+# Source the GNUstep environment
+source /usr/local/share/GNUstep/Makefiles/GNUstep.sh
+
+# Clone the repository
+git clone --branch <REPLACE_WITH_LATEST_TAG> https://github.com/gnustep/libs-corebase
+
+cd libs-corebase
+./configure
+```
+
+If you are only interested in using non-graphical frameworks you can stop here.

source/Guides/Setup/Linux/index.md

@@ -0,0 +1,42 @@
+# Linux
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents
+:titlesonly: true
+
+building-linux
+```
+
+## Installation (simple)
+
+Ensure you have `bash`, `curl`, and `sudo` installed and working. Then run the following command in your terminal:
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/gnustep/tools-scripts/master/gnustep-web-install)"
+```
+
+This will install GNUstep with most modern features enabled, including a recent version of Clang, support for ARC and other modern Objective-C features, typed selectors, ICU support in NSString, NSLocale, and similar classes, and Grand Central Dispatch. It installs from the `master` or `main` branch of most repositories.
+
+Avoid your distribution packages -- it is often outdated and sometimes is compiled using GCC, which disables ARC and modern Objective-C features.
+
+## Code completion, navigation, and linting
+
+### VSCode or VSCodium
+
+We use the clangd extension, which provides support for code completion and navigation, along with Clang-style warnings and error messages, based on the Clang compiler's code. If you have the Microsoft C/C++ extension, make sure to disable IntelliSense when prompted, as IntelliSense does not support Objective-C and Objective-C++ code.
+
+Here is the list of extensions:
+- [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) - The official clang language server for Visual Studio Code
+
+You need to explicitly set the clangd executable path in the clangd extension settings if you want to use the system version of LLVM. You can find the clangd executable in the LLVM installation directory (e.g. `C:\Program Files\LLVM\bin\clangd.exe`).
+
+You can now open a folder in Visual Studio Code, and start coding. The clangd extension will search for the file `compile_commands.json` to get the compiler flags. 
+
+To build your project, simply use the integrated terminal.
+
+Behaviour with different build systems:
+- Meson: Generates `compile_commands.json` by default
+- CMake: Generates `compile_commands.json` with the `-DCMAKE_EXPORT_COMPILE_COMMANDS=1` flag
+- Make: Intercept and generate `compile_commands.json` with the [bear](https://github.com/rizsotto/Bear) tool
+  - Run Make using `bear -- make` in order to generate a `compile_commands.json` file

source/Guides/Setup/Windows/building-windows-msvc.md

@@ -0,0 +1,62 @@
+# Building on Windows
+
+As building the GNUstep toolchain on Windows is a bit more involved than on other platforms, we have a dedicated build script for it.
+
+The toolchain is used commercially as well, and can be used to integrate Objective-C into your existing Windows projects.
+
+## 1 Prerequisites
+
+Before we can start building, we need to install some dependencies. We will be using [Chocolatey](https://chocolatey.org/) to install them.
+
+Follow the guide on installing Visual Studio, and the Windows SDK from the [Windows Development Workflow](./windows-dev-workflow.md) guide.
+
+### 1.1 Installing other dependencies
+
+Now install the following dependencies using chocolatey:
+
+```sh
+choco install llvm git msys2 nasm
+choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
+```
+
+We use LLVM and the clang frontend to compile Objective-C code, and lld as a linker.
+
+MSYS2 is a software distribution and a development platform for Windows, providing a
+Unix-like environment, a package management system (based on pacman), and tools
+for bridging Windows idiosyncrasies with the Unix world.
+
+### 1.2 Installing msys2 packages
+
+Now we need to install some packages using pacman, the package manager of MSYS2.
+Open a MSYS2 shell (Windows + R -> msys2.exe), and run the following commands:
+
+```sh
+pacman -S --needed make autoconf automake libtool pkg-config
+```
+
+### 2 Building
+
+We can start building the toolchain. Open a MSYS2 shell, and clone the tools-windows-msvc repository:
+
+```sh
+# Export the path to the LLVM and Git binaries
+export PATH=$PATH:/c/Program\ Files/Git/cmd:/c/Program\ Files/LLVM/bin
+
+# Clone the repository (you can change the installation directory)
+cd /c
+git clone https://github.com/gnustep/tools-windows-msvc
+```
+
+Open a x64 Native Tools Command Prompt (search for it in the start menu) and run the build.bat script:
+
+```sh
+cd C:\tools-windows-msvc
+
+# You can omit the type to build debug, and release, or change it to Debug
+# We only build non-gui libraries (libobjc2, libdispatch, base, corebase)
+# If you want to build the gui libraries, you can remove the --no-gui flag
+build.bat --type Release --no-gui
+```
+
+If no error occured during the build, you can now find the toolchain in `C:\GNUstep\x64\{Debug, Release}`.
+To learn more about the toolchain directory structure and how to use it, see [Using the MSVC toolchain](./using-windows-msvc.md).

source/Guides/Setup/Windows/ide-setup.md

@@ -0,0 +1,20 @@
+# IDE setup
+
+## 3 Code completion, navigation, and linting
+
+### 3.1 Using Visual Studio Code
+
+We use a combination of the Microsoft C/C++ extension, and the clangd extension. Make sure to disable IntelliSense when prompted, as IntelliSense does not support Objective-C and Objective-C++ code.
+
+Here is the list of extensions:
+- [C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) - IntelliSense, debugging, and code browsing for C and C++
+- [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) - The official clang language server for Visual Studio Code
+
+You need to explicitly set the clangd executable path in the clangd extension settings if you want to use the system version of LLVM. You can find the clangd executable in the LLVM installation directory (e.g. `C:\Program Files\LLVM\bin\clangd.exe`).
+
+You can now open a folder in Visual Studio Code, and start coding The clangd extension will search for the file `compile_commands.json` to get the compiler flags. 
+
+Behaviour with different build systems:
+- Meson: Generates `compile_commands.json` by default
+- CMake: Generates `compile_commands.json` with the `-DCMAKE_EXPORT_COMPILE_COMMANDS=1` flag
+- Make: Intercept and generate `compile_commands.json` with the [bear](https://github.com/rizsotto/Bear) tool

source/Guides/Setup/Windows/index.md

@@ -0,0 +1,15 @@
+# Windows
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents
+:titlesonly: true
+
+sdk-setup
+installing-windows-msvc
+using-windows-msvc-msys2
+building-windows-msvc
+ide-setup
+```
+
+First, you should set up a development environment following [the SDK setup guide](sdk-setup). Then you can either [build GNUstep](building-windows-msvc) or [install GNUstep from the prebuilt binaries](installing-windows-msvc). Then, [set up and use GNUstep in MSYS2](using-windows-msvc-msys2) and [set up VS Code](ide-setup).

source/Guides/Setup/Windows/installing-windows-msvc.md

@@ -0,0 +1,52 @@
+# Installing the GNUstep MSVC toolchain on Windows
+
+We call the native GNUstep toolchain for Windows the MSVC (Microsoft Visual C++) toolchain, as it uses the MSVC compiler for some projects,
+and uses native Windows APIs, instead of a POSIX compatibility layer like MinGW. It also produces native Windows binaries.
+
+Clang is used for compiling Objective-C code.
+
+## 1 Prerequisites
+
+First we need to install LLVM, to get the clang frontend, and lld. We will be using [Chocolatey](https://chocolatey.org/) to install it, but you can also install it manually using the official installer.
+
+In a Administrator Shell (either CMD or Powershell), run the following command:
+```sh
+choco install llvm
+```
+
+## 2 Installing from a prebuilt release
+
+We provide prebuilt releases of the toolchain, which you can download from the [releases page](https://github.com/gnustep/tools-windows-msvc/releases) on GitHub. Select the latest release, and download `GNUstep-Windows-MSVC-x64.zip` artefact
+if you are on a x86_64 system.
+
+Extract the zip file to a directory of your choice. We will use `C:\GNUstep` in this guide, as it is also the default installation directory of the build script.
+
+You can now use the toolchain, and start building your own projects.
+
+## 3 Structure of the toolchain directory
+
+If you are familiar with the standard filesystem structure on UNIX-based system, you will find some similarities here.
+`C:\GNUstep\x64` contains two directories: Debug and Release. The debug build contains debug symbols (.pdb files for dlls).
+
+```sh
+$ ls GNUstep/x64/Debug
+bin  etc  include  lib  share
+```
+
+The `bin` directory contains binaries, and dlls (objc.dll, gnustep-base-1_28.dll, etc).
+```sh
+$ ls GNUstep/x64/Debug/bin
+HTMLLinker.exe  defaults.exe  gnustep-base-1_28.dll   gnustep-corebase-0.pdb  icuin72.dll  libffi-8.dll  make_strings.exe  opentool     plget.exe    plutil.exe
+autogsdoc.exe   dispatch.dll  gnustep-base-1_28.pdb   gnustep-tests           icuio72.dll  libffi-8.pdb  objc.dll          pl.exe       plmerge.exe  sfparse.exe
+cvtenc.exe      dispatch.pdb  gnustep-config          gspath.exe              icutu72.dll  libiconv.dll  objc.pdb          pl2link.exe  plparse.exe  xmlparse.exe
+debugapp        gdnc.exe      gnustep-corebase-0.dll  icudt72.dll             icuuc72.dll  libiconv.pdb  openapp           pldes.exe    plser.exe
+```
+
+The `lib` directory contains static libraries (.lib files).
+```
+$ ls GNUstep/x64/Debug/lib
+GNUstep  dispatch.lib  exslt.lib  ffi.lib  gnustep-base.lib  gnustep-corebase.lib  iconv.lib  icudt.lib  icuin.lib  icuio.lib  icutest.lib  icutu.lib  icuuc.lib  objc.lib  pkgconfig  xml2.lib  xslt.lib
+```
+
+The `include` directory contains the headers for the libraries (you will recognise the `Foundation` subdirectory containing the header files). The `share` directory contains the GNUstep configuration files.
+