ObjFW  Documentation

There are three ways you are probably reading this right now:

  • On ObjFW's homepage, via Fossil's web interface
  • On GitHub
  • 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?

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 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 a developer does not need to concern themselves with portability and making sure their code works with multiple frameworks: Instead, if it works it 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
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
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 three licenses:

The QPL allows you to use ObjFW in any open source project. Because the GPL does not allow using code under any other license, ObjFW is also available under the GPLv2 and GPLv3 to allow GPL-licensed projects to use ObjFW.

You can pick under which of those three licenses you want to use ObjFW. If none of them 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.

Cloning the repository

ObjFW is developed in a Fossil 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 .frameworks 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 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 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. 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.

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. 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.

In order to build the documentation yourself (necessary to have documentation for trunk / master), you need to have Doxygen 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 in the bug tracker.

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:

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.

Thanks

  • Thank you to Jonathan Neuschäfer for reviewing the entirety (all 84k LoC at the time) of ObjFW's codebase in 2017!
  • Thank you to Hill Ma for donating an M1 Mac Mini to the project in 2022!

Commercial use

If for whatever reason neither the terms of the QPL nor those of the GPL 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.