Skip to content

Latest commit

 

History

History
288 lines (183 loc) · 12 KB

INSTALL.md

File metadata and controls

288 lines (183 loc) · 12 KB

Étoilé INSTALL

WARNING: As it stands now, Étoilé is more or less a development environment and not a desktop environment. We have no working theme since we are still in the process of migrating from our Camaelon theme engine to the new one bundled with GNUstep. User-oriented applications such as Melodie can fail to launch or behave correctly because their development have been put on hold. We advise you not to use the session support built into Étoilé, but rather write Étoilé code inside another environment such as GNOME or KDE.

Required software

  • LLVM/Clang 3.3 is required to build Étoilé

LLVM/Clang 3.3 binaries can be downloaded here.

Warning: For now, LLVM/Clang trunk is not supported for LanguageKit.

GCC is not supported, although it can be used to build some modules within the repository (especially GCC 4.6 which supports the main Objective-C 2 features).

You need to have the GNUstep core libraries installed in order to compile and use Étoilé. The core packages are, at a minimum:

  • gnustep-make 2.6.6 or higher
  • gnustep-base trunk (1.24.6 misses some APIs required by CoreObject)
  • gnustep-gui trunk
  • gnustep-back trunk
  • libobjc2 trunk (other ObjC runtimes such as the one packaged with GCC won't work, and libobjc2 1.7 has buggy weak reference support)

Warning: libobjc2 is also known as the GNUstep runtime. It's a new runtime unrelated to the GCC libobjc and the old GNUstep libobjc (which was a just patched GCC libobjc). Linux distributions such as Debian or Ubuntu include packages named libobjc2 or libobjc3 which are completely unrelated to the GNUstep runtime, and are just recent GCC libobjc packaged under a new name. More details in GNUstep Objective-2 FAQ

GNUstep source releases can be downloaded here and the libobjc2 source here.

Alternatively you can check out the latest GNUstep unstable (or trunk) as follows, but libobjc2 won't be included:

svn co http://svn.gna.org/svn/gnustep/modules/core

Note: EtoileUI works best with the most recent GNUstep svn revision, many EtoileUI-related bug fixes or improvements are regularly being committed to the GNUstep repository.

You need some extra libraries if you intend to build a complete Etoile environment or the whole repository:

For libdispatch, packaged versions on Linux or FreeBSD are not compatible with libobjc2. For now, we maintain our own libdispatch. To install it, check out and follow the libdispatch-objc2/INSTALL document (you must install libobjc2 first, see Build and Install GNUstep section):

git clone https://github.com/etoile/libdispatch-objc2

If you are using LLVM/Clang and GNUstep packages rather than building them manually, you can jump directly to the section Build and Install Etoile. Don't forget to check libobjc2 is installed, otherwise you have to install it as explained in the Build and Install GNUstep section.

Notation

In the following sections, square brackets "[ ]" are used to indicate an optional parameter.

Build LLVM and Clang

  • First check out the projects

      svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm
  cd llvm/tools
  svn co http://llvm.org/svn/llvm-project/cfe/trunk clang

  • Build both projects but don't install them

    It's a good idea to build LLVM in parallel, so use -j if you can

      cd .. # Back to llvm directory
  ./configure [--enable-optimized] && make [-j4]

    Both LLVM and Clang have been built in debug mode.

    Without --enable-optimized, Clang is quite slow, so it can be a good idea to pass this option. The downside is that it makes harder to debug LLVM/Clang issues, which might lead you to recompile LLVM/Clang without --enable-optimized later on.

    For more detailed instructions, see http://clang.llvm.org/get_started.html

  • Finally expose LLVM and Clang:

      export PATH=$PATH:$PWD/Debug/bin: # llvm/Debug/bin contains the clang binary
  export CC=clang # Make Clang the C/ObjC compiler rather than GCC

    A good choice is put the two lines above in ~/.bashrc or similar and open a new shell. This way you won't have to export these variable every time you want to compile GNUstep or Étoilé stuff.

  • Check Clang is ready:

      clang -v

Build and Install GNUstep

To build GNUstep with Clang:

  • Check out GNUstep core modules and libobjc2:

      svn co http://svn.gna.org/svn/gnustep/modules/core
  svn co http://svn.gna.org/svn/gnustep/libs/libobjc2/trunk libobjc2

  • Install GNUstep Make a first time:

      cd core/make
  ./configure --enable-debug-by-default --with-layout=gnustep [--prefix=/]
  make && sudo -E make install
  . /usr/GNUstep/System/Library/Makefiles/GNUstep.sh
  # Or . /System/Library/Makefiles/GNUstep.sh if --prefix=/ was passed

    A good choice is to put this last line above in ~/.bashrc or similar. This way you won't have to source GNUstep.sh every time you want to compile GNUstep or Etoile stuff.

    Note: If you use a C shell, you should source GNUstep.csh rather than GNUstep.sh.

  • Build libobjc2

    Install/strip ensures you can debug ObjC code without stepping inside runtime functions each time a message is sent.

      cd ../../libobjc2
  mkdir Build
  cd Build
  cmake -DCMAKE_CXX_COMPILER=clang++ -DTESTS=FALSE ..
  make && sudo -E make install/strip

    A special sudo invocation for make install will be required if sudo uses a secure PATH variable:

      make && sudo sh -c "." $GNUSTEP_MAKEFILES/GNUstep.sh; make install/strip

    You can also edit /etc/sudoers using visudo and comment out the line Defaults secure_path=XXX. Which means sudo -E now inherits the PATH variable as customized by GNUstep.sh and the gnustep-config tool can be found (by the libobjc2 GNUmakefile). If the secure path support has been disabled, sudo -E make install will work as is to install GNUstep and Etoile, in the next instructions.

    Warning: The new runtime is the GNU runtime version 2 but its library version is libobjc.so.4. libobjc.so.2 corresponds to the GNU runtime version 1 which comes with GCC and is also available at http://svn.gna.org/svn/gnustep/dev-libs/libobjc.

  • Install GNUstep Make a second time so it can detect the new ObjC runtime just installed:

      cd ../../../core/make
  ./configure --enable-debug-by-default --enable-objc-nonfragile-abi --with-layout=gnustep [--prefix=/]
  make && sudo -E make install

  • Build and Install GNUstep Base, Gui and Back:

      cd ../../core/base
  # For Linux e.g. Ubuntu, --with-ffi-include is usually required
  ./configure --disable-mixedabi [--with-ffi-include=/usr/include/`gcc -dumpmachine`]
  make && sudo -E make install

  cd ../../core/gui
  ./configure && make && sudo -E make install

  cd ../../core/back
  ./configure && make && sudo -E make install

    You can check you are really using Clang and not GCC with make messages=yes instead of make when building a GNUstep module. You can switch back to GCC for a given project with make CC=gcc (or alternatively ./configure CC=gcc).

    To get an overview of the build options per module, you can use ./configure --help in each module directory.

    See also GNUstep for further information.

Build and Install Étoilé

Note: If you encounter path related error, you can source GNUstep.sh or GNUstep.csh in your shell, read the GNUstep documentation to know more about this topic.

  • Build and Install libdispatch (requires CMake 2.8 or higher)

      cd ../..
  git clone https://github.com/etoile/libdispatch-objc2
  # For more detailed instructions, see libdispatch-lobjc2/INSTALL
  mkdir libdispatch-objc2/Build
  cd libdispatch-objc2/Build
  cmake -DCMAKE_C_COMPILER=clang -DCMAKE_BUILD_TYPE=Release ..
  make && sudo -E make install

  • Build and Install Etoile:

    Go to the Etoile directory that contains this INSTALL document

      make # Don't use -j flag
  [sudo] [-E] make install

    Warning: If Smalltalk.h not found is reported, then it is usually because the -jflag was passed to GNUstep Make. GNUstep Make sometimes doesn't track the dependencies correctly for compiling SmalltalkParser.

Uninstall Étoilé

Go to the Etoile directory that contains this INSTALL document

[sudo] [-E] make uninstall

Custom Build and Install

In order to build and install the whole project (with the exception of developers tools like UnitKit), you can just type in the root directory (named Etoile):

make
[sudo] [-E] make install

You can choose to build only custom set of modules. Add a 'modules.make' file in the root directory named 'Etoile' that contains Frameworks, Services and so on. In this file, to turn on the module CoreObject and off the module UnitKit, write:

export coreobject = yes
export unitkit = no

Be careful to have no trailing spaces after 'yes' or 'no'. Take also note by declaring these variables, you only determine whether these specific modules are built or not, but the build system won't automatically resolve and turn on and off dependencies in relation to those modules. So you must keep track by yourself of the dependencies to be enabled or disabled. These dependencies are usually documented in Frameworks/GNUmakefile and similar directories. They can also always be found by looking at the linker flags for each module GNUmakefile.

You can use the 'make' command with all the available options from every projects directory.

You can also build test bundles for any specified modules by adding an option 'test=yes', in future you should be able to run every test bundles with 'make check' but this is not implemented currently.

Generate Documentation

To build both the code and the documentation at the same time in any directory, type:

make documentation=yes

In addition, you can also generate the documentation without building the code per module. Move to a module directory (e.g. cd Languages/LanguageKit) and do:

make doc

Every time you generate some documentation, a Documentation directory appears per module (e.g. Languages/LanguageKit/Documentation) and it gets consolidated in Developer/Documentation. You can browse the Developer/Documentation/index.html as a starting point. If you are in a module directory, you can browse its documentation with Documentation/index.html (e.g. Languages/LanguageKit/Documentation/index.html)

To clean the generated documentation in the current module directory (will also clean the content copied in Developer/Documentation):

make clean-doc

Finally to remove all the generated documentation, you can use in any directory:

make distclean

which also discards the code previously built.

Trouble

Give us feedback! Tell us what you like; tell us what you think could be better. Send bug reports and patches to https://github.com/etoile/Etoile.