Blame README

ff2181
sofort: portable software project template
ff2181
------------------------------------------
ff2181
ff2181
This README file aims to speed-up the initial use of sofort
ff2181
with your own project while accounting for diverse groups
ff2181
of learners.
ff2181
ff2181
On that note, and in addition to making the most out of this document,
ff2181
you might want to join the (un)usually friendly #midipix channel on
ff2181
the freenode irc network.
ff2181
ff2181
======================================================================
ff2181
ff2181
LEARN BY COMPARISON:
ff2181
ff2181
# git clone git://midipix.org/sofort
ff2181
# git clone git://midipix.org/mdso
ff2181
# diff -u  sofort/config.project mdso/config.project
ff2181
# diff -ru sofort/project        mdso/project
ff2181
ff2181
======================================================================
ff2181
ff2181
LEARN BY EXAMPLE:
ff2181
ff2181
* mdso: basic configuration, explicit source list
ff2181
https://git.midipix.org/cgit.cgi/mdso/
ff2181
ff2181
* bfirm: an external build project for libfirm, using wildcards
ff2181
  in project/common.mk and project/headers.mk.
ff2181
https://git.midipix.org/cgit.cgi/compilers/bfirm/
ff2181
ff2181
* sbpython3: an external build project for python3.x, utilizing
ff2181
  sofort's config test framework (cfgtest.sh) and a custom config
ff2181
  step (project/config/cfgdefs.sh).
ff2181
ff2181
======================================================================
ff2181
ff2181
LEARN BY INSTRUCTION:
ff2181
ff2181
First Use-Case: using sofort with an existing project
ff2181
-- keep your original repository and the build project separate;
ff2181
-- allow testing the new build system (sofort) against the old one;
ff2181
-- merge the two at the time of your choice.
ff2181
ff2181
-- for the purpose of illustration:
ff2181
:: foo  (directory containing your original project)
ff2181
:: bfoo (directory containing the new build project)
ff2181
:: temp (where you'll run configure, which could be bfoo or elsewhere)
ff2181
ff2181
* copy all files and folders from the top-level sofort repository
ff2181
  into bfoo; the _include_ and _src_ sub-directories are place-holders,
ff2181
  and may thus be removed.
ff2181
ff2181
* edit config.project: ignoring the #_build section for the time being,
ff2181
  and keeping all three components (front-end, shared, static) disabled.
ff2181
ff2181
* test that everything is ready:
ff2181
  cd temp && /path/to/bfoo/configure --source-dir=/path/to/foo && make
ff2181
ff2181
* the default location for public (api) headers is include/foo/
ff2181
ff2181
* edit project/common.mk and project/headers.mk. Whether you use
ff2181
  wildcards or explicit references to source files and headers is
ff2181
  entirely up to you, and bears no effect on the build process.
ff2181
ff2181
* edit config.project again, and enable the relevant component(s), that
ff2181
  is, any or all of front-end, shared, and static); note also that you
ff2181
  may remove whichever portion of config.project that is irrelevant to
ff2181
  your project.
ff2181
ff2181
* test again.
ff2181
ff2181
Second Use-Case: using sofort with a new project
ff2181
-- keeping everything under a single repository;
ff2181
-- no need to pass --source-dir=/path/to/foo to configure;
ff2181
-- otherwise identical to the first use-case, as outlined above.
ff2181
ff2181
======================================================================