1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
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
|
