Index: README.md
==================================================================
--- README.md
+++ README.md
@@ -1,429 +1,13 @@
-There are three ways you are probably reading this right now:
-
- * On [ObjFW](https://objfw.nil.im/)'s homepage, via Fossil's web interface
- * On [GitHub](https://github.com/ObjFW/ObjFW)
- * Via an editor or pager, by opening `README.md` from a clone or tarball
-
-ObjFW is developed using Fossil, so if you are reading this on GitHub or any
-other place, you are most likely using a mirror.
-
-
-
Table of Contents
-
- * [What is ObjFW?](#what)
- * [Installation](#installation)
- * [License](#license)
- * [Releases](#releases)
- * [Cloning the repository](#cloning)
- * [Building from source](#building-from-source)
- * [macOS and iOS](#macos-and-ios)
- * [Building as a framework](#building-framework)
- * [Using the macOS or iOS framework in Xcode](#framework-in-xcode)
- * [Broken Xcode versions](#broken-xcode-versions)
- * [Windows](#windows)
- * [Getting MSYS2](#getting-msys2)
- * [Setting up MSYS2](#setting-up-msys2)
- * [Getting, building and installing ObjFW](#steps-windows)
- * [Nintendo DS, Nintendo 3DS and Wii](#nintendo)
- * [Nintendo DS](#nintendo-ds)
- * [Nintendo 3DS](#nintendo-3ds)
- * [Wii](#wii)
- * [Amiga](#amiga)
- * [Writing your first application with ObjFW](#first-app)
- * [Documentation](#documentation)
- * [Bugs and feature requests](#bugs)
- * [Support and community](#support)
- * [Donating](#donating)
- * [Thanks](#thanks)
- * [Commercial use](#commercial-use)
-
-
-What is ObjFW?
-
- ObjFW is a portable, lightweight framework for the Objective-C language. It
- enables you to write an application in Objective-C that will run on any
- [platform](PLATFORMS.md) supported by ObjFW without having to worry about
- differences between operating systems or various frameworks you would
- otherwise need if you want to be portable.
-
- It supports all modern Objective-C features when using Clang, but is also
- compatible with GCC ≥ 4.6 to allow maximum portability.
-
- ObjFW is intentionally incompatible with Foundation. This has two reasons:
-
- * GNUstep already provides a reimplementation of Foundation, which is only
- compatible to a certain degree. This means that a developer still needs to
- care about differences between frameworks if they want to be portable. The
- idea behind ObjFW is that developers do not need to concern themselves
- with portability and making sure their code works with multiple
- frameworks: Instead, if it works with ObjFW on one platform, they can
- reasonably expect it to also work with ObjFW on another platform. ObjFW
- behaving differently on different operating systems (unless inevitable
- because it is a platform-specific part, like the Windows Registry) is
- considered a bug and will be fixed.
- * Foundation predates a lot of modern Objective-C concepts. The most
- prominent one is exceptions, which are only used in Foundation as a
- replacement for `abort()`. This results in cumbersome error handling,
- especially in initializers, which in Foundation only return `nil` on error
- with no indication of what went wrong. It also means that the return of
- every `init` call needs to be checked against `nil`. But in the wild,
- nobody actually checks *each and every* return from `init` against `nil`,
- leading to bugs. ObjFW fixes this by making exceptions a first class
- citizen.
-
- ObjFW also comes with its own lightweight and extremely fast Objective-C
- runtime, which in real world use cases was found to be significantly faster
- than both GNU's and Apple's runtime.
-
-
-Installation
-
- ObjFW packages are available for various operating systems and can be
- installed as following:
-
- Operating System | Command
- ---------------------------|---------------------------------------------
- Alpine Linux | `doas apk add objfw`
- CRUX | `sudo prt-get depinst objfw`
- Debian | `sudo apt install objfw`
- Fedora | `sudo dnf install objfw`
- FreeBSD | `sudo pkg install objfw`
- Haiku | `pkgman install objfw`
- Haiku (gcc2h) | `pkgman install objfw_x86`
- macOS (Homebrew) | `brew install objfw`
- macOS (pkgsrc) | `cd $PKGSRCDIR/devel/objfw && make install`
- NetBSD | `cd /usr/pkgsrc/devel/objfw && make install`
- OpenBSD | `doas pkg_add objfw`
- OpenIndiana | `sudo pkg install developer/objfw`
- Ubuntu | `sudo apt install objfw`
- Windows (MSYS2/CLANG64) | `pacman -S mingw-w64-clang-x86_64-objfw`
- Windows (MSYS2/CLANGARM64) | `pacman -S mingw-w64-clang-aarch64-objfw`
- Windows (MSYS2/UCRT64) | `pacman -S mingw-w64-ucrt-x86_64-objfw`
- Windows (MSYS2/MINGW32) | `pacman -S mingw-w64-i686-objfw`
-
- If your operating system is not listed, you can
- build ObjFW from source.
-
-
-License
-
- ObjFW is released under the GNU Lesser General Public License version 3.0.
-
- If this license does not work for you, contact me and we can find a solution.
-
-
-Releases
-
- Releases of ObjFW, as well as change logs and the accompanying documentation,
- can be found [here](https://objfw.nil.im/wiki?name=Releases).
-
-
-Cloning the repository
-
- ObjFW is developed in a [Fossil](https://fossil-scm.org) repository, with
- automatic incremental exports to Git. This means you can either clone the
- Fossil repository or the Git repository - it does not make a huge difference.
- The main advantage of cloning the Fossil repository over cloning the Git
- repository is that you also get all the tickets, wiki pages, etc.
-
-Fossil
-
- Clone the Fossil repository like this:
-
- fossil clone https://objfw.nil.im
-
- You can then use Fossil's web interface to browse the timeline, tickets,
- wiki pages, etc.:
-
- cd objfw
- fossil ui
-
- In order to verify the signature of the currently checked out checkin, you
- can use:
-
- fossil artifact current | gpg --verify
-
- Please note that not all checkins are signed, as the signing key only resides
- on trusted systems. This means that checkins I perform on e.g. Windows are
- unsigned. However, usually it should not take long until there is another
- signed checkin. Alternatively, you can go back until the last signed checkin
- and review changes from there on.
-
-Git
-
- To clone the Git repository, use the following:
-
- git clone https://github.com/ObjFW/ObjFW
-
- Git commits are not signed, so if you want to check the signature of an
- individual commit, branch head or tag, please use Fossil.
-
-Building from source
-
- To build ObjFW from source and install it, just run the following commands:
-
- ./configure
- make
- make check
- sudo make install
-
- In case you checked out ObjFW from the Fossil or Git repository, you need to
- run the following command first:
-
- ./autogen.sh
-
-macOS and iOS
-
-Building as a framework
-
- When building for macOS or iOS, everything is built as a `.framework` by
- default if `--disable-shared` has not been specified to `./configure`. The
- frameworks will end up in `$PREFIX/Library/Frameworks`.
-
- To build for macOS, just follow the
- regular instructions above.
-
- To build for iOS, follow the regular instructions, but instead of
- `./configure` do something like this:
-
- clang="xcrun --sdk iphoneos clang"
- export OBJC="$clang -arch arm64e -arch arm64"
- export OBJCPP="$clang -arch arm64e -E"
- export IPHONEOS_DEPLOYMENT_TARGET="10.0"
- ./configure --prefix=/usr/local/ios --host=arm64-apple-darwin
-
- To build for the iOS simulator, follow the regular instructions, but instead
- of `./configure` use something like this:
-
- clang="xcrun --sdk iphonesimulator clang"
- export OBJC="$clang -arch $(uname -m)"
- export IPHONEOS_DEPLOYMENT_TARGET="10.0"
- ./configure --prefix=/usr/local/iossim --host=$(uname -m)-apple-darwin
-
-Using the macOS or iOS framework in Xcode
-
- To use the macOS framework in Xcode, you need to add the `.framework`s to
- your project and add the following flags to `Other C Flags`:
-
- -fconstant-string-class=OFConstantString -fno-constant-cfstrings
-
-Broken Xcode versions
-
- Some versions of Xcode shipped with a version of Clang that ignores
- `-fconstant-string-class=OFConstantString`. This will manifest in an error
- like this:
-
- OFAllocFailedException.m:94:10: error: cannot find interface declaration for
- 'NSConstantString'
- return @"Allocating an object failed!";
- ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 1 error generated.
-
- Unfortunately, there is no workaround for this other than to
- upgrade/downgrade Xcode or to build upstream Clang yourself.
-
- In particular, Xcode 11 Beta 1 to Beta 3 are known to be affected. While
- Xcode 11 Beta 4 to Xcode 11.3 work, the bug was unfortunately reintroduced in
- Xcode 11.4.1 and was only fixed in Xcode 12 Beta 1.
-
- You can get older versions of Xcode
- [here](https://developer.apple.com/download) by clicking on "More" in the
- top-right corner.
-
-Windows
-
- Windows is only officially supported when following these instructions, as
- there are many MinGW versions that behave slightly differently and often
- cause problems.
-
-Getting MSYS2
-
- The first thing to install is [MSYS2](https://www.msys2.org) to provide a
- basic UNIX-like environment for Windows. Unfortunately, the binaries are not
- signed, so make sure you download it via HTTPS. However, packages you
- download and install via MSYS2 are cryptographically signed.
-
-Setting up MSYS2
-
- MSYS2 currently supports 7 different
- [environments](https://www.msys2.org/docs/environments/). All of them except
- for the one called just "MSYS" are supported, but which packages you need to
- install depends on the environment(s) you want to use. If you only want to
- target Windows 10 and newer, the CLANG64 and CLANG32 environments are the
- recommended ones.
-
- For CLANG64, use:
-
- pacman -Syu mingw-w64-clang-x86_64-clang \
- mingw-w64-clang-x86_64-fossil \
- mingw-w64-clang-x86_64-openssl
-
- For CLANG32, use:
-
- pacman -Syu mingw-w64-clang-i686-clang \
- mingw-w64-clang-i686-fossil \
- mingw-w64-clang-i686-openssl
-
- For CLANGARM64, use (you need to use Fossil via another environment):
-
- pacman -Syu mingw-w64-clang-aarch64-clang mingw-w64-clang-aarch64-openssl
-
- For MINGW64, use:
-
- pacman -Syu mingw-w64-x86_64-clang \
- mingw-w64-x86_64-fossil \
- mingw-w64-x86_64-openssl
-
- For MINGW32, use:
-
- pacman -Syu mingw-w64-i686-clang \
- mingw-w64-i686-fossil \
- mingw-w64-i686-openssl
-
- For UCRT64, use:
-
- pacman -Syu mingw-w64-ucrt-x86_64-clang \
- mingw-w64-ucrt-x86_64-fossil \
- mingw-w64-ucrt-x86_64-openssl
-
- When using `pacman` to install the packages, `pacman` might tell you to close
- the window. If it does so, close the window, restart MSYS2 and execute the
- `pacman` command again.
-
- There is nothing wrong with installing multiple environments, as MSYS2 has
- created shortcuts for each of them in your start menu. Just make sure to use
- the correct shortcut for the environment you want to use.
-
- Finally, install a few more things that are common between all environments:
-
- pacman -S autoconf automake make
-
-Getting, building and installing ObjFW
-
- Start the MSYS2 using the shortcut for the environment you want to use and
- check out ObjFW:
-
- fossil clone https://objfw.nil.im
-
- You can also download a release tarball if you want. Now `cd` to the newly
- checked out repository and build and install it:
-
- ./autogen.sh && ./configure && make -j16 install
-
- If everything was successful, you can now build projects using ObjFW for
- Windows using the normal `objfw-compile` and friends.
-
-Nintendo DS, Nintendo 3DS and Wii
-
- Download and install [devkitPro](https://devkitpro.org/wiki/Getting_Started).
-
-Nintendo DS
-
- Follow the normal process, but instead of `./configure` run:
-
- ./configure --host=arm-none-eabi --with-nds
-
-Nintendo 3DS
-
- Follow the normal process, but instead of `./configure` run:
-
- ./configure --host=arm-none-eabi --with-3ds
-
-Wii
-
- Follow the normal process, but instead of `./configure` run:
-
- ./configure --host=powerpc-eabi --with-wii
-
-Amiga
-
- Install [amiga-gcc](https://github.com/bebbo/amiga-gcc). Then follow the
- normal process, but instead of `./configure` run:
-
- ./configure --host=m68k-amigaos
-
-
-Writing your first application with ObjFW
-
- To create your first, empty application, you can use `objfw-new`:
-
- objfw-new --app MyFirstApp
-
- This creates a file `MyFirstApp.m`. The `-[applicationDidFinishLaunching:]`
- method is called as soon as ObjFW finished all initialization. Use this as
- the entry point to your own code. For example, you could add the following
- line there to create a "Hello World":
-
- [OFStdOut writeLine: @"Hello World!"];
-
- You can compile your new app using `objfw-compile`:
-
- objfw-compile -o MyFirstApp MyFirstApp.m
-
- `objfw-compile` is a tool that allows building applications and libraries
- using ObjFW without needing a full-blown build system. If you want to use
- your own build system, you can get the necessary flags from `objfw-config`.
-
-
-Documentation
-
- You can find the documentation for released versions of ObjFW
- [here](https://objfw.nil.im/docs/).
-
- In order to build the documentation yourself (necessary to have documentation
- for trunk / master), you need to have [Doxygen](https://www.doxygen.nl)
- installed. Once installed, you can build the documentation from the root
- directory of the repository:
-
- make docs
-
-
-Bugs and feature requests
-
- If you find any bugs or have feature requests, please
- [file a new bug](https://objfw.nil.im/tktnew) in the
- [bug tracker](https://objfw.nil.im/reportlist).
-
- Alternatively, feel free to send a mail to js@nil.im!
-
-
-Support and community
-
- If you have any questions about ObjFW or would like to talk to other ObjFW
- users, the following venues are available:
-
- * The [forum](https://objfw.nil.im/forum)
- * A [Matrix room](https://matrix.to/#/%23objfw:nil.im)
- * A [Discord room](https://objfw.nil.im/discord), bridged to the Matrix
- room above
- * A [Telegram room](https://t.me/objfw), bridged to the Matrix room above
- * A [Slack room](https://objfw.nil.im/slack), bridged to the Matrix room
- above
- * An IRC channel named `#objfw` on `irc.oftc.net`
- ([Web chat](https://webchat.oftc.net/?channels=%23objfw)), bridged to the
- Matrix room above
-
- Please don't hesitate to join any or all of those!
-
-
-Donating
-
- If you want to donate to ObjFW, you can read about possible ways to do so
- [here](https://objfw.nil.im/wiki?name=Donating).
-
-
-Thanks
-
- * Thank you to [Jonathan Neuschäfer](https://github.com/neuschaefer) for
- reviewing the *entirety* (all 84k LoC at the time) of ObjFW's codebase in
- 2017!
- * Thank you to [Hill Ma](https://github.com/mahiuchun) for donating an M1 Mac
- Mini to the project in 2022!
-
-
-Commercial use
-
- If for whatever reason the terms of GNU Lesser General Public License version
- 3.0 don't work for you, a proprietary license for ObjFW including support is
- available upon request. Just write a mail to js@nil.im and we can find a
- reasonable solution for both parties.
+ObjFW is a portable, lightweight framework for the Objective-C language. It
+enables you to write an application in Objective-C that will run on any
+supported by ObjFW without having to worry about differences between operating
+systems or various frameworks you would otherwise need if you want to be
+portable.
+
+It supports all modern Objective-C features when using Clang, but is also
+compatible with GCC ≥ 4.6 to allow maximum portability.
+
+ObjFW is intentionally incompatible with Foundation.
+
+You can read more about ObjFW on its [homepage](https://objfw.nil.im),
+including how to install and use it.