diff options
Diffstat (limited to 'HOWTO')
| -rw-r--r-- | HOWTO | 110 |
1 files changed, 110 insertions, 0 deletions
@@ -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 |