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://foss21.org/sofort
# git clone git://foss21.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.foss21.org/cgit.cgi/mdso/

* bfirm: an external build project for libfirm, using wildcards
  in project/common.mk and project/headers.mk.
https://git.foss21.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.

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