From ff2181d75363793135517064440aaddaf4513da7 Mon Sep 17 00:00:00 2001 From: midipix Date: Tue, 1 Jan 2019 07:09:47 -0500 Subject: sofort: added a newly purposed README document. --- README | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 README (limited to 'README') 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. + +====================================================================== -- cgit v1.2.3