You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
137 lines
5.5 KiB
Plaintext
137 lines
5.5 KiB
Plaintext
Installing the GNUstep Objective-C Runtime
|
|
==========================================
|
|
|
|
This file describes how to configure, install, and package the Objective-C
|
|
runtime. Note that although this runtime should build with gcc, it is strongly
|
|
recommended that you compile it with clang and clang++ as your [Objective-]C and
|
|
[Objective-]C++ compilers.
|
|
|
|
Basic Building
|
|
--------------
|
|
|
|
The runtime uses cmake to build. CMake performs configuration and generates
|
|
things that can be used by other programs that actually perform the building.
|
|
I recommend that you use Ninja for building if you are compiling regularly, but
|
|
these instructions will use Make to avoid the need for an extra dependency.
|
|
|
|
After checking out the code, build as follows:
|
|
|
|
$ mkdir Build
|
|
$ cd Build
|
|
$ cmake ..
|
|
-- { Lots of cmake output }
|
|
-- Build files have been written to: /build_path/libobjc/Build
|
|
$ make -j8
|
|
{ lots of make output }
|
|
[100%]...
|
|
$ sudo -E make install
|
|
|
|
This will build the runtime with the default options for your platform, which
|
|
may or may not be what you want, but hopefully are. You can see the list of
|
|
configurable options, and short explanations of each one, with this command
|
|
from the build directory:
|
|
|
|
$ ccmake .
|
|
|
|
This will also allow you to make changes. If you prefer a GUI, then there is
|
|
almost certainly a CMake GUI for your platform, but documenting them all is
|
|
beyond the scope of this quick guide.
|
|
|
|
If you have gcc and clang both installed, then cmake currently defaults to
|
|
selecting gcc. You should override this by adding `-DCMAKE_C_COMPILER=clang
|
|
-DCMAKE_CXX_COMPILER=clang++` to your Objective-C flags.
|
|
|
|
|
|
Running the Tests
|
|
-----------------
|
|
|
|
By default, a load of test cases will be built. If you are compiling with gcc,
|
|
you probably want to turn them off: most of them will fail, and a lot won't
|
|
even compile. At present, they all should pass with clang 3.3 and most with
|
|
clang 3.2. If you have built the tests, you can run them with the test target,
|
|
like this:
|
|
|
|
$ make test
|
|
...
|
|
100% tests passed, 0 tests failed out of 28
|
|
|
|
Total Test time (real) = 4.23 sec
|
|
|
|
|
|
If your compiler can't build the tests, or you are building a package and don't
|
|
want to bother running the tests then add `-DTESTS=OFF` to your `cmake` command
|
|
line.
|
|
|
|
C++ Runtime Integration
|
|
-----------------------
|
|
|
|
The runtime will attempt to link against the C++ runtime library, if it is
|
|
available as a shared library on your platform. The two supported
|
|
implementations are libcxxrt (shipped with FreeBSD and written by the author of
|
|
this Objective-C runtime) and libsupc++ from the GNU project. If these are
|
|
available, then you will get a single libobjc.so, which links to either
|
|
libcxxrt or libsupc++. This linkage is required so that we can interoperate
|
|
with C++ exceptions, in particular catching Objective-C objects thrown from
|
|
Objective-C libraries in Objective-C++ `catch` blocks.
|
|
|
|
On most GNU/Linux systems, libstdc++ is statically linked to libsupc++. In
|
|
this configuration, we provide a separate libobjcxx.so, which avoids the need
|
|
for the Objective-C runtime to depend on the STL implementation just to be able
|
|
to interoperate with C++ exceptions.
|
|
|
|
Blocks Runtime Integration
|
|
--------------------------
|
|
|
|
libobjc2 ships with a runtime for the blocks C extension (i.e. closures/lambdas) and
|
|
will install compatibility headers for the libBlocksRuntime library that ships with
|
|
LLVM's compiler-rt or Swift's libdispatch. Alternatively, libobjc2 can be built without
|
|
the embedded blocks runtime and utilise the one from libdispatch instead. This can be
|
|
enabled by adding `-DEMBEDDED_BLOCKS_RUNTIME=OFF` to the `cmake` command. It's required
|
|
that your version of libBlocksRuntime provides the `Blocks_private.h` header.
|
|
(enabled with `-DINSTALL_PRIVATE_HEADERS=ON` when building libdispatch from source)
|
|
|
|
Regardless of the chosen blocks runtime implementation, blocks will be fully integrated
|
|
into the Objective-C runtime.
|
|
|
|
Installation Location
|
|
---------------------
|
|
|
|
There are two ways of installing the runtime. It can either be treated as a
|
|
system library or a GNUstep library. It is recommended for packagers to use
|
|
the former, but people building GNUstep systems to do the latter.
|
|
|
|
If the build system detects the presence of the `gnustep-config` utility, it
|
|
will default to a GNUstep install, in the installation domain specified by this
|
|
utility. You can explicitly specify the installation domain by setting the
|
|
`GNUSTEP_INSTALL_TYPE` property to either `LOCAL`, `SYSTEM`, `NETWORK`, or
|
|
`NONE`. If you select `NONE` then the library will be installed in the
|
|
standard system location for libraries. This is configured by setting the
|
|
`CMAKE_INSTALL_PREFIX` variable, and typically defaults to either `/usr/` or
|
|
`/usr/local`.
|
|
|
|
LLVM Optimisations
|
|
------------------
|
|
|
|
The library comes with an LLVM plugin that provides a number of optimisations
|
|
that are specific to code compiled for this runtime. This is built by default
|
|
if the LLVM CMake modules are found. To disable building these optimisations,
|
|
run cmake with the `-DLLVM_OPTS=OFF` flag.
|
|
|
|
Packaging
|
|
---------
|
|
|
|
The build system support CPack, and so can build RPM and DEB packages out of
|
|
the box. Select the packaging system by setting the `CPACK_GENERATOR` property
|
|
and then build with the package target. For example, to build a .deb:
|
|
|
|
$ mkdir Deb
|
|
$ cd Deb
|
|
$ cmake .. -DCPACK_GENERATOR=DEB
|
|
$ make -j8
|
|
$ make package
|
|
|
|
Note that you almost certainly want to set CMAKE_BUILD_TYPE to Release when
|
|
packaging. Debug builds are slower and will print extra messages to help with
|
|
development. This is useful when writing Objective-C code, but not as useful
|
|
for end users.
|