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