[Official Mirror] A portable framework for the Objective-C language.
There are three ways you are probably reading this right now:
README.mdfrom a checkout 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.
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:
abort(). This results in cumbersome error handling, especially in initializers, which in Foundation only return
nilon error with no indication of what went wrong. It also means that the return of every
initcall needs to be checked against
nil. But in the wild, nobody actually checks each and every return from
initagainst
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.
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 of ObjFW, as well as changelogs and the accompanying documentation can be found here.
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.
Clone the Fossil repository like this:
$ fossil clone https://objfw.nil.im objfw.fossil $ mkdir objfw && cd objfw $ fossil open ../objfw.fossil
You can then use Fossil's web interface to browse the timeline, tickets, wiki pages, etc.:
$ fossil ui
It's also possible to open the same local repository multiple times, so that you have multiple working directories all backed by the same local repository.
In order to verify the signature of the currently checked out checkin, you can use:
$ fossil artifact current | gpg --verify
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.
To install ObjFW, just run the following commands:
$ ./configure $ make $ make install
In case you checked out ObjFW from the Fossil or Git repository, you need to run the following command first:
$ ./autogen.sh
When building for macOS or iOS, everything is built as a
.frameworkby default if
--disable-sharedhas not been specified to
configure.
To build for iOS, use something like this:
$ clang="clang -isysroot $(xcrun --sdk iphoneos --show-sdk-path)" $ export OBJC="$clang -arch armv7 -arch arm64" $ export OBJCPP="$clang -arch armv7 -E" $ export IPHONEOS_DEPLOYMENT_TARGET="9.0" $ ./configure --prefix=/usr/local/ios --host=arm-apple-darwin
To build for the iOS simulator, use something like this:
$ clang="clang -isysroot $(xcrun --sdk iphonesimulator --show-sdk-path)" $ export OBJC="$clang -arch i386 -arch x86_64" $ export OBJCPP="$clang -arch i386 -E" $ export IPHONEOS_DEPLOYMENT_TARGET="9.0" $ ./configure --prefix=/usr/local/iossim --host=i386-apple-darwin
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
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 is only officially supported when following these instructions, as there are many MinGW versions that behave slightly differently and often cause problems.
The first thing to install is MSYS2 to provide a basic UNIX-like environment for Windows. Unfortunately, the binaries are not signed and there is no way to verify their integrity, so only download this from a trusted connection. Everything else you will download using MSYS2 later will be cryptographically signed.
The first thing to do is updating MSYS2. It is important to update things in a certain order, as
pacman(the package manager MSYS2 uses, which comes from Arch Linux) does not know about a few things that are special on Windows.
First, update the mirror list:
$ pacman -Sy pacman-mirrors
Then proceed to update the
msys2-runtimeitself,
bashand
pacman:
$ pacman -S msys2-runtime bash pacman mintty
Now close the current window and restart MSYS2, as the current window is now defunct. In a new MSYS2 window, update the rest of MSYS2:
$ pacman -Su
Now you have a fully updated MSYS2. Whenever you want to update MSYS2, proceed in this order. Notice that the first
pacmaninvocation includes
-yto actually fetch a new list of packages.
Now it's time to install MinGW-w64. If you want to build 32 bit binaries:
$ pacman -S mingw-w64-i686-clang mingw-w64-i686-gcc-objc
For 64 bit binaries:
$ pacman -S mingw-w64-x86_64-clang mingw-w64-x86_64-gcc-objc
There is nothing wrong with installing them both, as MSYS2 has created two entries in your start menu:
MinGW-w64 Win32 Shelland
MinGW-w64 Win64 Shell. So if you want to build for 32 or 64 bit, you just start the correct shell.
Finally, install a few more things needed to build ObjFW:
$ pacman -S autoconf automake fossil make
Start the MinGW-w64 Win32 or Win64 Shell (depening on what version you want to build - do not use the MSYS2 Shell shortcut, but use the MinGW-w64 Win32 or Win64 Shell shortcut instead!) and check out ObjFW:
$ fossil clone https://objfw.nil.im objfw.fossil $ mkdir objfw && cd objfw $ fossil open ../objfw.fossil
You can also download a release tarball if you want. Now go to the newly checked out repository and build and install it:
$ ./autogen.sh && ./configure && make -j16 install
If everything was successfully, you can now build projects using ObjFW for Windows using the normal
objfw-compileand friends.
Download and install devkitPro.
Follow the normal process, but instead of
./configurerun:
$ ./configure --host=arm-none-eabi --with-nds
Follow the normal process, but instead of
./configurerun:
$ ./configure --host=arm-none-eabi --with-3ds
Follow the normal process, but instead of
./configurerun:
$ ./configure --host=powerpc-eabi --with-wii
Install amiga-gcc. Then follow the normal process, but instead of
./configurerun:
$ ./configure --host=m68k-amigaos
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":
[of_stdout writeLine: @"Hello World!"];
You can compile your new app using
objfw-compile:
$ objfw-compile -o MyFirstApp MyFirstApp.m
objfw-compileis 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.
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
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 [email protected]!
If you have any questions about ObjFW or would like to talk to other ObjFW users, the following venues are available:
#objfwon
irc.oftc.net(Web chat), bridged to the Matrix room above
Please don't hesitate to join any or all of those!
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 [email protected] and we can find a reasonable solution for both parties.