diff --git a/README.md b/README.md
index 4471d1b..b01bc18 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,12 @@
-GNUstep Windows MSVC Toolchain
-==============================
+# GNUstep Windows MSVC Toolchain
[](https://github.com/gnustep/tools-windows-msvc/actions/workflows/ci.yml?query=branch%3Amaster)
-This project comprises a collection of scripts to build a modern GNUstep toolchain, with support for blocks and Automatic Reference Counting (ARC), using Clang and the Visual Studio toolchain with the MSVC ABI. The toolchain can then be used to integrate Objective-C code in any Windows app, without using MinGW.
+This project comprises a collection of scripts to build a modern GNUstep toolchain, with support for blocks and Automatic Reference Counting (ARC), using LLVM/Clang and the Visual Studio toolchain. The toolchain can be used to integrate Objective-C code in any Windows app, including Visual Studio projects (see below), without using MinGW.
-Libraries
----------
+## Libraries
The toolchain currently consists of the following libraries:
@@ -23,14 +21,14 @@ The toolchain currently consists of the following libraries:
- [ICU](https://docs.microsoft.com/en-us/windows/win32/intl/international-components-for-unicode--icu-) (using system-provided DLL on Windows 10 version 1903 or later)
-Installation
-------------
+## Installation
-To install a pre-built release, download it from [the releases on GitHub](https://github.com/gnustep/tools-windows-msvc/releases) and unpack it into into `C:\GNUstep` (this location is required if you plan on using the `gnustep-config` script).
+To install a pre-built release, download it from [the releases on GitHub](https://github.com/gnustep/tools-windows-msvc/releases) and unpack it into into `C:\GNUstep` (this location is only required if you plan on using the `gnustep-config` script, otherwise any location will work).
+You should end up with the folders `C:\GNUstep\x64\Debug` and `C:\GNUstep\x64\Release` when using the x64 toolchain. The explanations below and the example project assume this installation location.
-Using the Toolchain
--------------------
+
+## Using the Toolchain from the Command Line
Building and linking Objective-C code using the toolchain and `clang` requires a number of compiler and linker flags.
@@ -48,7 +46,7 @@ When building in a Bash environment (like an MSYS2 shell), the `gnustep-config`
The `clang-cl` driver can also be used to build Objective-C code, but requires prefixing some of the options using the `-Xclang` modifier to pass them directly to Clang:
# build test.m to produce an object file test.obj
- clang-cl -I C:\GNUstep\x64\Debug\include -fobjc-runtime=gnustep-2.0 -Xclang -fexceptions -Xclang -fobjc-exceptions -fblocks -DGNUSTEP -DGNUSTEP_WITH_DLL -DGNUSTEP_RUNTIME=1 -D_NONFRAGILE_ABI=1 -D_NATIVE_OBJC_EXCEPTIONS -DGSWARN -DGSDIAGNOSE /MDd /c test.m
+ clang-cl -I C:\GNUstep\x64\Debug\include -fobjc-runtime=gnustep-2.0 -Xclang -fexceptions -Xclang -fobjc-exceptions -fblocks -DGNUSTEP -DGNUSTEP_WITH_DLL -DGNUSTEP_RUNTIME=1 -D_NONFRAGILE_ABI=1 -D_NATIVE_OBJC_EXCEPTIONS /MDd /c test.m
# link object file into executable
clang-cl test.obj gnustep-base.lib objc.lib dispatch.lib /MDd -o test.exe
@@ -58,16 +56,110 @@ Specify `/MDd` for debug builds, and `/MD` for release builds, in order to link
Note that the `GNUSTEP_WITH_DLL` definition is always required to enable annotation of the Objective-C objects defined in the GNUstep Base DLL with `__declspec(dllexport)`.
-Status and Known Issues
------------------------
+## Using the Toolchain in Visual Studio
+
+The [examples/ObjCWin32](examples/ObjCWin32) folder contains a Visual Studio project that is set up with support for Objective-C.
+
+Following are instructions to set up your own project, or add Objective-C support to an existing Win32 Visual Studio project.
+
+### Create the Project
+
+Launch Visual Studio, select "Create a new project", and select a project template that is compatible with C++/Win32, e.g. Console App, Windows Desktop Application, Static Library, Dynamic-Link Library (DLL). In the following we assume we are building a Console App.
+
+Choose a name for the project and create the project. In this example, we choose ObjCHello.
+
+### Edit the Project
+
+#### Edit Project Properties
+
+1. Right click the project in Solution Explorer, and select Properties.
+2. In "General" change "Platform Toolset" to LLVM (clang-cl). MSVC does not support compiling Objective-C source files.
+3. In "VC++ Directories" add the following for toolchain headers and libraries to be found:
+ * Include Directories: `C:\GNUstep\$(LibrariesArchitecture)\$(Configuration)\include`
+ * Library Directories: `C:\GNUstep\$(LibrariesArchitecture)\$(Configuration)\lib`
+4. Set required preprocessor definitions in C/C++ > Preprocessor > Preprocessor Definitions:
+ `GNUSTEP;GNUSTEP_WITH_DLL;GNUSTEP_RUNTIME=1;_NONFRAGILE_ABI=1;_NATIVE_OBJC_EXCEPTIONS`
+5. Add required compiler options in C/C++ > Command Line > Additional Options:
+ `-fobjc-runtime=gnustep-2.0 -Xclang -fexceptions -Xclang -fobjc-exceptions -fblocks -Xclang -fobjc-arc`
+ Leave out the last option if you don't want to use Automatic Reference Counting (ARC).
+6. Link required libraries in Linker > Input > Additional Dependencies:
+ `gnustep-base.lib;objc.lib;dispatch.lib`
+
+#### Edit Project File
+
+1. Right click the project in Solution Explorer and select "Unload Project".
+2. Double click on the project again and to open the raw vcxproj file.
+3. Above the last line `` add the following to copy the GNUstep DLLs to the output directory.
+ ```
+
+
+ PreserveNewest
+ %(Filename)%(Extension)
+
+
+ ```
+4. Right click the project in Solution Explorer and select "Reload Project".
+
+#### Edit Source File Properties
+
+1. Right click on the `ObjCHello.cpp` source file and rename it to `ObjCHello.m` (or `ObjCHello.mm` for Objective-C++).
+2. Right click on the `ObjCHello.m` file and select Properties.
+3. In C/C++ > Advanced, clear the "Compile As" option. This tells MSBuild to not set /TP or /TC flags when compiling the file and build the file as Objective-C(++) based on the file extension.
+
+### Add Objective-C Code and Run
+
+Now you can start writing your Objective-C code in the `ObjCHello.m` file. You can test the setup by replacing the content of the file with:
+
+```objective-c
+#include
+
+int main(int argc, char *argv[])
+{
+ NSLog(@"Hello Objective-C");
+ return 0;
+}
+```
+
+Place a breakpoint at the line `NSLog(@"Hello Objective-C");` and run from Visual Studio. You should see the breakpoint getting hit, and the log printed in the "Output" panel when you continue.
+
+
+## Status and Known Issues
The toolchain is fully usable on x64. On x86, libdispatch is not available due to a [build error](https://bugs.swift.org/browse/SR-14314).
Note that GNUstep support for Windows is not as complete as on Unixes, and some [tests in GNUstep Base](https://github.com/gnustep/libs-base/actions/workflows/main.yml?query=branch%3Amaster) are still failing.
-Prerequisites for Building
---------------------------
+## Troubleshooting
+
+### Compile Errors
+
+* `'Foundation/Foundation.h' file not found`
+Please ensure that you correctly set "Include Directories".
+
+* `#import of type library is an unsupported Microsoft feature`
+Please ensure that you have cleared the "Compile As" property of the file.
+
+### Link Errors
+
+* `cannot open input file 'gnustep-base.lib'`
+Please ensure that you correctly set "Library Directories".
+
+* ` unresolved external symbol __objc_load referenced in function .objcv2_load_function`
+Please ensure that you added the required linking options in Linker > Input > Additional Dependencies.
+
+* `relocation against symbol in discarded section: __start_.objcrt$SEL`
+Please ensure that you include some Objective-C code in your project. (This is currently required due to a [compiler/linker issue](https://github.com/llvm/llvm-project/issues/49025) when using the LLD linker. Alternatively you can use link.exe instead of LLD.)
+
+### Runtime Errors
+
+* `The code execution cannot proceed because gnustep-base-1_28.dll was not found. Reinstalling the program may fix this problem.`
+Please ensure that DLLs are copied to the output folder.
+
+
+## Building the Toolchain
+
+### Prerequisites
Building the toolchain require the following tools to be installed and available in the PATH. Their presence is verified when building the toolchain.
@@ -92,9 +184,9 @@ The MSYS2 installation is required to provide the Bash shell and Unix tools requ
These can be installed via Pacman inside a MSYS2 shell:
`pacman -S --needed make autoconf automake libtool pkg-config`
+Please make sure that you do _not_ have `gmake` installed in your MSYS2 environment, as it is not compatible but will be picked up by the project Makefiles. Running `which gmake` in MSYS2 should print "which: no gmake in ...".
-Building the Toolchain
-----------------------
+### Building
Run the [build.bat](build.bat) script in either a x86 or x64 Native Tools Command Prompt from Visual Studio to build the toolchain for x86 or x64.
diff --git a/USAGE.md b/USAGE.md
deleted file mode 100644
index bdde10d..0000000
--- a/USAGE.md
+++ /dev/null
@@ -1,135 +0,0 @@
-### Prerequisite
-
-1. [Microsoft Visual Studio 2019 or later](https://visualstudio.microsoft.com/downloads/) (You should install **Desktop development with C++** in workload and **C++ Clang Compiler for Windows**, **C++ Clang-cl for build tools (x64/x86)** in Invidual components)
-2. [GNUstep Windows MSVC Toolchain](https://github.com/gnustep/tools-windows-msvc/releases)
-
-### Preparation
-
-#### Install GNUstep Windows MSVC Toolchain
-
-Extract the toolchain from the .zip file you downloaded. It is recommended you extract the `GNUstep` folder to `C:\` so the toolchain will be organized like `C:\GNUstep\x86[x64]\Debug[Release]`. You can use a different path, but note that some configuration files have the path hardcoded.
-
-To go from here, we assume we are building an x64 app/dll and we are using `C:\GNUstep\x64\Debug` as the toolchain root.
-
-### Create Project
-
-Launch Visual Studio, select "Create a new project". There are many projects to choose from, ensure that you choose one that is compatible with C++/Win32. For example: Console App, Windows Desktop Application, Static Library, Dynamic-Link Library (DLL).
-
-To go from here, we assume we are building a Console App.
-
-We choose a name for the project and create the project. In this example, we choose ObjCHello.
-
-When the project is created, change current configuration to Debug, x64.
-
-### Edit Project
-
-#### Edit Project Properties
-
-1. Right click on the ObjCHello project in Solution Explorer, and select Properties.
-
-2. In General, change Platform Toolset to LLVM (clang-cl). MSVC does not support compiling Objective-C source files.
-3. In VC++ Directories, add `C:\GNUstep\x64\Debug\include` to Include Directories, and `C:\GNUstep\x64\Debug\lib` to Library Directories. To ensure toolchain headers and libraries can be correctly found.
-4. In C/C++ -> Preprocessor, add the followings to Preprocessor Definitions.
-
-```
-GNUSTEP
-GNUSTEP_WITH_DLL
-GNUSTEP_RUNTIME=1
-_NONFRAGILE_ABI=1
-_NATIVE_OBJC_EXCEPTIONS
-GSWARN
-GSDIAGNOSE
-```
-
-5. In C/C++ -> Command Line, add `-fobjc-runtime=gnustep-2.0 -Xclang -fexceptions -Xclang -fobjc-exceptions -fblocks -Xclang -fobjc-arc ` to Additional Options. It does not have to be perfect match, if you do not use ARC, you can pass `-fno-objc-arc` instead.
-6. In Linker -> Input, add the library you need to Additional Dependencies, for example
-
-```
-gnustep-base.lib
-objc.lib
-dispatch.lib
-```
-
-#### Edit Project File
-
-1. Right click on the ObjCHello project in Solution Explorer, and select Unload Project.
-
-2. Double click on the project again and it should present you the raw vcxproj file.
-
-3. Under this line ``, add the following lines to tell MSBuild to use MSVC Linker (link.exe) instead of LLVM Linker (lld-link.exe) because lld-link.exe will throw error.
-
- ```
-
- link.exe
-
- ```
-
-4. Above the closing line of `` add the following lines to copy GNUstep DLLs to output directory.
-
- ```
-
-
- PreserveNewest
- %(Filename)%(Extension)
-
-
- ```
-
-5. Right click on the ObjCHello project in Solution Explorer, and select Reload Project.
-
-#### Edit File Properties
-
-1. Right click on the `ObjCHello.cpp` that the project comes with and rename it to `ObjCHello.m`. (Or `ObjCHello.mm` in Objective-C++).
-2. Right click on the `ObjCHello.m` file and select Properties.
-3. In C/C++ -> Advanced, clear the Compile As. This tells MSBuild to not set /TP or /TC flags when compiling the file.
-
-### Write Code and Run
-
-Now you can start writing your Objective-C code in the `ObjCHello.m` file. You can test the setup by replacing the content of the file with
-
-```objective-c
-#include
-
-int main(int argc, char *argv[])
-{
- NSLog(@"Hello Objective-C");
- return 0;
-}
-```
-
-Placing a breakpoint at line `NSLog(@"Hello Objective-C");` and run from Visual Studio, you should be seeing the breakpoint getting hit.
-
-### Troubleshooeting
-
-#### Compile Error
-
-1. `'Foundation/Foundatiosn.h' file not found`
-
-Please ensure that you correctly set Include Directories.
-
-2. `#import of type library is an unsupported Microsoft feature`
-
-Please ensure that you have cleared the Compile As property of the file.
-
-#### Link Error
-
-1. `cannot open input file 'gnustep-base.lib'`
-
-Please ensure that you correctly set Library Directories.
-
-2. ` unresolved external symbol __objc_load referenced in function .objcv2_load_function`
-
-Please ensure that you correctly set Linker -> Input.
-
-3. `relocation against symbol in discarded section: __start_.objcrt$SEL`
-
-Please ensure that you have changed the linker to link.exe.
-
-#### Runtime Error
-
-`The code execution cannot proceed because gnustep-base-1_28.dll was not found. Reinstalling the program may fix this problem.`
-
-Please ensure that DLLs are copied to the output folder.
-
-
-