| 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, Makefile.in, sysinfo/version.sh, |
| sofort/defs.mk, sofort/custom.mk, 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 |