ObjFW  Diff

Differences From Artifact [711c05e9ce]:

To Artifact [6e10392554]:


1
2
3
4
5
6
7
8
9
10
11
12
13

14
15
16
17

18
19
20
21
22
23
24
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

18
19
20
21
22
23
24
25













+



-
+







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.


<h1 id="table-of-contents">Table of Contents</h1>

 * [What is ObjFW?](#what)
 * [Installation](#installation)
 * [License](#license)
 * [Releases](#releases)
 * [Cloning the repository](#cloning)
 * [Installation](#installation)
 * [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)
50
51
52
53
54
55
56
57

58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76


























77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

97
98
99
100
101
102
103
51
52
53
54
55
56
57

58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

123
124
125
126
127
128
129
130







-
+



















+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+



















-
+








  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 portablility and making sure their code works with multiple
     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.


<h1 id="installation">Installation</h1>

  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/MINGW32)    | `pacman -S mingw-w64-i686-objfw`
  Windows (MSYS2/CLANG64)    | `pacman -S mingw-w64-clang-x86_64-objfw`
  Windows (MSYS2/CLANGARM64) | `pacman -S mingw-w64-clang-aarch64-objfw`

  If your operating system is not listed, you can
  <a href="#building-from-source">build ObjFW from source</a>.  


<h1 id="license">License</h1>

  ObjFW is released under three licenses:

   * [QPL](LICENSE.QPL)
   * [GPLv2](LICENSE.GPLv2)
   * [GPLv3](LICENSE.GPLv3)

  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.


<h1 id="releases">Releases</h1>

  Releases of ObjFW, as well as changelogs and the accompanying documentation
  Releases of ObjFW, as well as change logs and the accompanying documentation,
  can be found [here](https://objfw.nil.im/wiki?name=Releases).


<h1 id="cloning">Cloning the repository</h1>

  ObjFW is developed in a [Fossil](https://fossil-scm.org) repository, with
  automatic incremental exports to Git. This means you can either clone the
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

145
146

147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167

168
169
170
171
172
173
174
175




176
177
178
179
180
181
182


183
184
185


186
187
188
189
190
191
192
140
141
142
143
144
145
146




147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166

167
168

169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189

190
191
192
193
194




195
196
197
198
199
200
201
202
203


204
205



206
207
208
209
210
211
212
213
214







-
-
-
-




















-
+

-
+




















-
+




-
-
-
-
+
+
+
+





-
-
+
+
-
-
-
+
+








  You can then use Fossil's web interface to browse the timeline, tickets,
  wiki pages, etc.:

    $ cd objfw
    $ 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

  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.

<h2 id="cloning-git">Git</h2>

  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.

<h1 id="installation">Installation</h1>
<h1 id="building-from-source">Building from source</h1>

  To install ObjFW, just run the following commands:
  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

<h2 id="macos-and-ios">macOS and iOS</h2>

<h3 id="building-framework">Building as a framework</h3>

  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
  <a href="#installation">regular instructions</a> above.
  <a href="#building-from-source">regular instructions</a> above.

  To build for iOS, follow the regular instructions, but instead of
  `./configure` do 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"
    $ 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="clang -isysroot $(xcrun --sdk iphonesimulator --show-sdk-path)"
    $ export OBJC="$clang -arch arm64 -arch x86_64"
    $ clang="xcrun --sdk iphonesimulator clang"
    $ export OBJC="$clang -arch $(uname -m)"
    $ export OBJCPP="$clang -arch arm64 -E"
    $ export IPHONEOS_DEPLOYMENT_TARGET="9.0"
    $ ./configure --prefix=/usr/local/iossim --host=arm64-apple-darwin
    $ export IPHONEOS_DEPLOYMENT_TARGET="10.0"
    $ ./configure --prefix=/usr/local/iossim --host=$(uname -m)-apple-darwin

<h3 id="framework-in-xcode">Using the macOS or iOS framework in Xcode</h3>

  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
319
320
321
322
323
324
325
326

327
328
329
330
331
332
333
341
342
343
344
345
346
347

348
349
350
351
352
353
354
355







-
+








<h1 id="first-app">Writing your first application with ObjFW</h1>

  To create your first, empty application, you can use `objfw-new`:

    $ objfw-new --app MyFirstApp

  This creates a file `MyFirstApp.m`. The `-[applicationDidFinishLaunching]`
  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`:
364
365
366
367
368
369
370





371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397

398
399
400
401
402
403
404
405
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400







401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416

417
418
419
420
421
422
423
424
425







+
+
+
+
+



-
-
-
-
-
-
-
















-
+








<h1 id="support">Support and community</h1>

  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
   * A [Slack channel](https://objfw.nil.im/slack), bridged to the Matrix room
     above
   * A [Discord channel](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 [Gitter room](https://gitter.im/ObjFW/ObjFW), bridged to the Matrix room
     above

  Please don't hesitate to join any or all of those!


<h1 id="donating">Donating</h1>

  If you want to donate to ObjFW, you can read about possible ways to do so
  [here](https://objfw.nil.im/wiki?name=Donating).


<h1 id="thanks">Thanks</h1>

  * 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!
    Mini to the project in 2022!


<h1 id="commercial-use">Commercial use</h1>

  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.