diff options
Diffstat (limited to 'HOWTO')
| -rw-r--r-- | HOWTO | 113 |
1 files changed, 0 insertions, 113 deletions
@@ -1,113 +0,0 @@ -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://localhost - 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, config.usage, Makefile.in, - sofort/config.vars, sofort/defs.mk, sofort/flavor.mk, - sofort/pkgconf.mk, sofort/pkgconf.sh, and - sofort/version.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 |