summaryrefslogtreecommitdiff
path: root/HOWTO
diff options
context:
space:
mode:
Diffstat (limited to 'HOWTO')
-rw-r--r--HOWTO110
1 files changed, 110 insertions, 0 deletions
diff --git a/HOWTO b/HOWTO
new file mode 100644
index 0000000..ac3cb13
--- /dev/null
+++ b/HOWTO
@@ -0,0 +1,110 @@
+The purpose of this how-to is to help you transform the sofort
+project template into your own work-in-progress repository.
+
+So that all steps are concrete and fully defined, let us
+pretend that you would like to create a library and front-end
+utility named 'wonderer', and have accordingly chosen 'wndr'
+as your namespace prefix.
+
+
+OUTLINE
+-------
+step 1: clone.
+step 2: make this your own.
+step 3: create your first interface.
+
+
+step 1: clone
+-------------
+# ./sofort.sh -d $HOME/wonderer -p wonderer -n wndr
+# cd $HOME/wonderer
+# git init
+
+
+step 2: make this your own
+--------------------------
+* update the README file with a preliminary description
+ of your project.
+
+* update COPYING.WONDERER with your license of choice.
+
+* include/wonderer/wonderer.h: fix whitespace as needed.
+
+* src/wonderer.c: vermsg[]: replace git://midipix.org
+ with your own git host.
+
+* verify that all went well:
+
+# mkdir ../build && cd ../build
+# ../wonderer/configure && make
+
+* enjoy your skeleton by running bin/wonderer.
+
+* commit your changes (i.e. 'created skeleton').
+
+
+step 3: create your first interface
+-----------------------------------
+At the outset, adding a command-line interface involves
+the addition of an argv option record in conjunction
+with an option tag and a driver switch case.
+
+Unless a no-op, the above interface will correspond to
+either a flag in your common context structure (i.e.
+struct wndr_common_ctx), or an attribute in that structure,
+or both.
+
+Now let us practice all that while also looking at the two
+dummy interfaces which are part of sofort (note that these
+interfaces are *not* present in the generated project):
+
+* src/internal/wonderer_driver_impl.h: add a tag (see the
+ DUMMY and PROPERTY tags in the corresponding sofort file).
+
+* src/skin/wonderer_skin_default.c: add an argv option record;
+ if your option is associated with a finite set of values
+ (i.e. --fruit=apple|grape|orange) then you should take
+ advantage of the 'paradigm' member in struct argv_option
+ (see src/internal/argv/argv.h for the complete struct
+ definition).
+
+* src/driver/wndr_driver_ctx.c: add a switch case; depending
+ on the interface that you are adding, you will be either
+ setting a bit in one of the flag members of wndr_common_ctx
+ (in which case you should define a macro for that flag),
+ or assign the option value to an attribute in the above
+ context (in which case you should add an appropriate member
+ to the context structure). For the latter case, see the
+ handling of TAG_OUTPUT_DUMMY in the respective sofort file;
+ for the former, see the handling of TAG_OUTPUT_PROPERTY.
+
+* make use of the newly added flag/attribute in one or more
+ of your functions; remember to refer to your new source file
+ in project/common.src, and, assuming you would like to expose
+ it, add the function declaration to wonderer.h.
+
+* front-end utility (src/wonderer.c): if applicable, extend
+ wonderer_perform_unit_actions() so that it calls the above
+ (library) function as needed.
+
+
+what about attribution?
+-----------------------
+As far as I (Z. Gilboa) am concerned, no attribution
+beyond the copyright clause in argv.h is necessary.
+Should you wish to include a detailed attribution note
+with your project, however, you may find the following
+text useful:
+
+The starting point for this repository was a skeleton
+generated by 'sofort: portable software project template'
+(git://midipix.org/sofort, MIT licensed, see COPYING.SOFORT).
+
+The generated skeleton included the following elements:
++ the argv parser and usage screen generator (argv.h).
++ the build system (configure, Makefile.in, project/defs.mk).
++ the initial driver logic:
+ --> src/driver/namespace_driver_ctx.c
+ --> src/driver/namespace_unit_ctx.c
++ and initial input mapping logic:
+ --> src/logic/namespace_map_input.c