README

# CURIE-12: README #############################################################

Curie is a semi-high-level, C-based, non-ANSI, non-POSIX libc replacement. It is
designed to only support the bare minimum of functionality that is needed to get
some use out of the language - because of this, the library can be used to write
the tiniest of programmes in C.

# QUICK AND DIRTY: COMPILATION AND INSTALLATION ################################

All you need is a make programme that supports GNU make's extensions; then just
run the makefile like this:

    $ make PREFIX=/ install

--------------------------------------------------------------------------------

NOTE:
    Please take note of the library licence (the COPYING file), as well as the
    credits (the CREDITS file).

# MAKEFILE SUMMARY #############################################################

In short, the interesting makefile targets are 'build' (the default), 'test'
(to run test cases) and 'install' to copy the compiled library to somewhere the
system will find it. The 'install' target supports the typical PREFIX and
DESTDIR options with their normal meanings.

To compile projects that depend on Curie, either install Curie and then compile
those projects separately, or check out their sources as first-level
subdirectories of the Curie source tree. The makefiles check for the 'targets'
subdirectory, so if you had curie/targets and curie/duat/targets, and compiled
things in the curie/ directory, then the makefile would compile both curie and
duat in the same context (and the test and install targets would work just as
well).

# DETAILS ######################################################################

Curie uses a good, old-fashioned makefile to compile and install the library.
In order to compile the library, simply change to the root directory of the
Curie source directory and issue the 'make' command:

    $ make

This will create a directory '.build' and some support files in that directory.
Building the library will then commence directly and should - hopefully -
complete without any errors.

NOTE: Make sure you have a version of 'make' that supports the GNU make
      extensions and that your shell is a proper Bourne shell.

## INSTALLING CURIE ############################################################

Simply use the 'install' target, like so:

    $ make install

The makefiles support the PREFIX and DESTDIR parameters to determine where to
install to. DESTDIR can be used to choose a different root directory to copy
files to, which is useful when creating packages. PREFIX is used to supply an
FHS prefix - the default is /usr/local. Since this is a system library, you
would probably want to use:

    $ make PREFIX=/ install

## TEST CASES ##################################################################

Curie comes with a fairly large number of test cases, which you can run by
supplying the 'test' target to make:

    $ make test

## COMPILING DEPENDANT PROJECTS ################################################

Since Curie is a very basic, system-level library, it is desirable to use that
library in some way. Curie-based libraries and programmes may be compiled in
one of two ways: either you need to install Curie properly, or you need to copy
the dependant project's sources into Curie's source directory. The former is
fairly straightforward, but the latter may be more convenient, especially when
cross-compiling.

To compile Curie projects without first installing Curie, simply copy or check
out the other project in your Curie directory, then compile normally:

    $ cd curie
    $ git clone https://github.com/kyuba/duat.git
    $ make

You could also check out all of the Curie-related repositories side-by-side and
create a minimal Curie makefile in that top level directory:

    $ cd projects
    $ git clone https://github.com/kyuba/curie.git
    $ git clone https://github.com/kyuba/duat.git
    $ echo 'include curie/include/curie.mk' > makefile
    $ make

The 'include/curie.mk' file is also installed when installing Curie with the
'install' target. That way a typical Curie-baed project only needs to create a
minimal makefile that contains a single 'include curie.mk' command.

# TROUBLESHOOTING / KNOWN ISSUES ###############################################

## STACK PROTECTORS ############################################################

Compilation may crash or curie programmes may die/stall/eat all resources for no
apparent reason in the garbage collection phase if you have a gcc that has been
patched with SSP and SSP is enabled by default. If you experience any funky
issues and you have SSP enabled, add -fno-stack-protector to your CFLAGS while
compiling curie programmes.

Protip: if you're an application developer you should shun SSP at all costs and
instead just fix your (or others') code if it's broken. Do not confuse fighting
the symptoms with fixing the underlying issue, it's not the same, no matter what
your computer science teachers with a favour for java and no concept nor
understanding of pointers may have told you. SSP in all its forms is one of the
sad reasons why applications suck these days.

# CONTACT #####################################################################

Please try not to email project members directly. The commits do include email
addresses, but it would be much nicer if you tried to hop onto freenode's 
\#kyuba channel and ask your question there, first.