sofort: added a newly purposed README document.

1 files changed, 78 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..d46e91c
--- /dev/null
+++ b/README
@@ -0,0 +1,78 @@
+sofort: portable software project template
+------------------------------------------
+
+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: ignoring the #_build section for the time being,
+  and keeping all three components (front-end, shared, static) disabled.
+
+* 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.
+
+======================================================================