README

   1 ####################################################################
   2
   3      _             _       _______             _            _
   4     / /           / /     / _____/            / /          / /
   5    / /       _   / /__   / /____    _    _   / / _____    / /_
   6   / /       / / / __  \  \_____ \  / /  / / / / / __  \  / __ \
   7  / /_____  / / / /__/ /  _____/ / / /__/ / / / / /__/ / / /``\ \
   8 /_______/ /_/ /______/  /______/  \___  / /_/ / _____/ /_/   /_/
   9 ````````  ``  ```````   ```````    ``/ /  `` / /`````  ``    ``
  10                                     / /     / /
  11                                    /_/     /_/
  12                                    ``      ``
  13 ###################################################################
  14
  15   Table of Contents
  16
  17   1. Dependencies
  18     1.1 Supported Operating Systems
  19     1.2 Supported Compilers
  20     1.3 Additional Libraries
  21
  22   2. Build instructions
  23     2.1 Compiling the source code
  24     2.2 Installing
  25
  26   3. Acknowledgements
  27     3.1 Copyright and licensing
  28     3.2 Reporting bugs
  29
  30 ###########################################################
  31
  32   1. Dependencies
  33
  34     1.1 Supported Operating Systems
  35
  36        Currently, LibSylph can be run most Unix-systems, including, but not
  37        limited to, Linux, FreeBSD, Cygwin, Mac OS X, and a few others.
  38        In order for the binary relocation function to work (i.e.
  39        thisapp->getXXX() ), support for /proc/self/exe is required. On Mac OS X,
  40        the /proc filesystem is not enabled by default. However, OS X provides
  41        an alternate method for retrieving the full path to the running
  42        executable, therefore no extra software is needed to function correctly
  43        on Mac OS X.
  44
  45        Minimal support for Microsoft Windows is included as well. However, no
  46        prepackaged compiler for this platform meets the required features (see
  47        section 1.2), therefore LibSylph WON'T run by default on Microsoft Windows
  48        currently. You can always try to set up a conforming compiler yourself.
  49        For that reason, we do not support nor endorse LibSylph on Microsoft
  50        Windows. You will see that certain functionality might be flawed,
  51        lacking, or nonexistent on Windows. Please do not report this as a bug
  52        until official support is added.
  53
  54     1.2 Supported Compilers
  55
  56         As of now, only one specific compiler is supported: the GNU C++ compiler
  57         (g++), version 4.4.0 or later. LibSylph uses certain GNU C++
  58         specific extensions. Furthermore, support for certain C++0x constructs
  59         is required. At the day of writing this document, only the compiler
  60         mentioned above supports these extensions. In case you found another
  61         compiler to meet these requirements, please contact
  62         the LibSylph developers (see section 3.2)
  63
  64   2. Build Instructions
  65
  66     2.1 Compiling the source code
  67
  68         2.1.1 Dependencies
  69
  70             LibSylph depends on boehm-gc, icu, and gettext. You need to have
  71             these programs installed first. Please consult your operating
  72             system vendor's manuals or look at our wiki.
  73             If you want to run test cases, you need to have gtest installed
  74             as well. For more information about the unit test system, see
  75             section 2.3.
  76
  77        2.1.2 Building
  78
  79             To build the source code, issue the following commands:
  80
  81                  cmake .
  82                  make
  83
  84             Please note you might need to specify the path to a C++0x compiler
  85             explicitly by using `-DCMAKE_CXX_COMPILER=/path/to/c++'.
  86
  87             To enable debugging symbols and other useful debug output, such
  88             as debug logging, assertions, and line number information,
  89             pass `-DCMAKE_BUILD_TYPE=Debug -DSYLPH_DEBUG=1' to cmake. Read
  90             the CMake documentation for more information about additional
  91             parameters that control the build.
  92
  93     2.2 Installing
  94
  95         To install LibSylph, issue the following command as root (or your
  96         operating systems respective administrator account):
  97
  98               make install
  99
 100         By default, LibSylph will install in /usr/local. If this is not what
 101         you want, you need to pass the -DCMAKE_INSTALL_PREFIX=/your/prefix
 102         to cmake before the build.
 103
 104     2.3 Running the test suite
 105
 106         To run the test suite, issue the following command in the build
 107         directory:
 108
 109              make test
 110
 111         This will build and run the entire test suite. You need to have
 112         gtest (Google Test) installed for this. Please consult the manual
 113         of your operating system vendor on how to install this library.
 114
 115   3. Acknowledgements
 116
 117     3.1 Copyright and licensing
 118
 119         Please see the files `AUTHORS' and `COPYING' to see the names of the
 120         original authors and the license of the code, respectively.
 121
 122     3.2 Reporting bugs
 123
 124         Please report bugs to the libsylph-devel@lists.sf.net mailing list. You
 125         need to register in order to be able to send e-mails to this list.
 126         See https://lists.sf.net/lists/listinfo/libsylph-devel for more info
 127         on how to register. When submitting bug reports, please state the
 128         version of LibSylph used. If you aren't using the latest version from
 129         git, first look if your bug is already fixed. If it isn't, include
 130         a full description of what is going wrong, and any possible error
 131         messages.
 132
 133         Things you should mention:
 134             * Your operating system, including version. For Linux users, state
 135               your kernel version, architecture, and distro.
 136             * The version of your compiler.
 137             * The version of any other tools you are using important to the
 138               problem (including LibSylph!).
 139             * What you were trying to do, what actually happened, and how this
 140               is not what you expected. Perhaps it's a feature, and not
 141               a bug? ;)
 142             * If you can reproduce the bug, and so, under what conditions.
 143             * If the bug is specifically tied to a certain operating system, or
 144               if you tried reproducing the bug on another operating system.
 145             * A minimal test case showcasing the bug. In case this is not
 146               possible, step-by-step instructions on how to reproduce the bug.
 147               The test case should not contain anything more than necessary,
 148               and shouldn't link with any other libraries than the standard
 149               libraries and LibSylph. If a certain library is essential to
 150               demonstrate the problem, please make sure it's readily available.
 151             * Any error messages, including backtraces from a debugger in case
 152               of program-terminating bugs (e.g. overflows, exceptions, ...)
 153             * If you have one, a patch to fix the bug :)
 154
 155 ###########################################################