sofort: portable software project skeleton

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

This README file aims to speed-up the initial use of sofort

with your own project while accounting for diverse groups

of learners.

On that note, and in addition to making the most out of this document,

you might want to join the (un)usually friendly #midipix channel on

the freenode irc network.

======================================================================

LEARN BY COMPARISON:

# git clone git://midipix.org/sofort

# git clone git://midipix.org/mdso

# diff -u  sofort/config.project mdso/config.project

# diff -ru sofort/project        mdso/project

======================================================================

LEARN BY EXAMPLE:

* mdso: basic configuration, explicit source list

https://git.midipix.org/cgit.cgi/mdso/

* bfirm: an external build project for libfirm, using wildcards

  in project/common.mk and project/headers.mk.

https://git.midipix.org/cgit.cgi/compilers/bfirm/

* sbpython3: an external build project for python3.x, utilizing

  sofort's config test framework (cfgtest.sh) and a custom config

  step (project/config/cfgdefs.sh).

======================================================================

LEARN BY INSTRUCTION:

First Use-Case: using sofort with an existing project

-- keep your original repository and the build project separate;

-- allow testing the new build system (sofort) against the old one;

-- merge the two at the time of your choice.

-- for the purpose of illustration:

:: foo  (directory containing your original project)

:: bfoo (directory containing the new build project)

:: temp (where you'll run configure, which could be bfoo or elsewhere)

* copy all files and folders from the top-level sofort repository

  into bfoo; the _include_ and _src_ sub-directories are place-holders,

  and may thus be removed.

* edit config.project, keeping all three components (front-end, shared,

  static) disabled for the time being.

* test that everything is ready:

  cd temp && /path/to/bfoo/configure --source-dir=/path/to/foo && make

* the default location for public (api) headers is include/foo/

* edit project/common.mk and project/headers.mk. Whether you use

  wildcards or explicit references to source files and headers is

  entirely up to you, and bears no effect on the build process.

* edit config.project again, and enable the relevant component(s), that

  is, any or all of front-end, shared, and static); note also that you

  may remove whichever portion of config.project that is irrelevant to

  your project.

* test again.

Second Use-Case: using sofort with a new project

-- keeping everything under a single repository;

-- no need to pass --source-dir=/path/to/foo to configure;

-- otherwise identical to the first use-case, as outlined above.

======================================================================