Blame HOWTO

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