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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE>shellmod: Principles</TITLE>
<LINK HREF="intro-3.html" REL=next>
<LINK HREF="intro-1.html" REL=previous>
<LINK HREF="intro.html#toc2" REL=contents>
</HEAD>
<BODY>
<A HREF="intro-3.html">Next</A>
<A HREF="intro-1.html">Previous</A>
<A HREF="intro.html#toc2">Contents</A>
<HR>
<H2><A NAME="s2">2. Principles</A></H2>
<P>In this section we will see the basic layout of a shellmod script, how
to use it and how it communicate with Linuxconf.
<P>
<H2><A NAME="ss2.1">2.1 Components of the shellmod package</A>
</H2>
<P>The shellmod package provides the following parts:
<P>
<UL>
<LI>The shellmod utility used to run shellmod script without Linuxconf.
This utility is located in /usr/bin.</LI>
<LI>The shellmod module which allows shellmod script to interact
with Linuxconf. Note that a shellmod script can be used both
ways, either stand-alone or embedded in Linuxconf.</LI>
<LI>The shellmod-lib.sh function library. This is located in
/usr/lib/linuxconf/lib. This contains utility functions simplifying
shellmod scripts. This file must be sourced in all scripts.</LI>
<LI>Some sample script.</LI>
<LI>At some point, the package will contain some contrib scripts and
a browser will be designed to easily find and try those contrib
scripts. If you have written something general and useful,
send it on the Linuxconf mailing list, for inclusion in this package.</LI>
</UL>
<P>
<H2><A NAME="ss2.2">2.2 How to use shellmod scripts</A>
</H2>
<P>A script may be used either stand-alone or within Linuxconf. It can
be used both ways.
<P>
<H3>As a stand-alone utility</H3>
<P>To run a shellmod script, you either do
<P>
<BLOCKQUOTE><CODE>
<PRE>
shellmod path_of_the_script [ arguments ]
</PRE>
</CODE></BLOCKQUOTE>
<P>Or if the script start with <CODE>#!/usr/bin/shellmod</CODE>, you simply
run it like any utility. Note that in all cases, the script must
be executable (<CODE>chmod +x script</CODE>).
<P>
<H3>As a Linuxconf module</H3>
<P>To be used this way, it must be registered in Linuxconf. This is done
either interactively or using a special command line. The shellmod module
register its configuration menu in the <CODE>Control files and systems</CODE>
menu. You will find there a dialog to register your script. Just
enter the path of your script and that's it. The script will be
visible in Linuxconf at the next run.
<P>The script may be registered using the following command line. This
is especially useful if you include your script in a package and
would like to register the script in Linuxconf at package installation
(RPM packagers might consider the trigger facility to do this).
<P>
<BLOCKQUOTE><CODE>
<PRE>
linuxconf --modulemain shellmod --setmod script_path
</PRE>
</CODE></BLOCKQUOTE>
<P>Note that the <CODE>linuxconf --modulemain</CODE> construct is the normal
way to yield control to a module own command line: shellmod is not
different.
<P>You may unregister a script from Linuxconf by doing:
<P>
<BLOCKQUOTE><CODE>
<PRE>
linuxconf --modulemain shellmod --unsetmod script_path
</PRE>
</CODE></BLOCKQUOTE>
<P>Note that the above syntax replicate the way normal (C++) Linuxconf
modules may be registered and unregistered, by using the <CODE>linuxconf --setmod</CODE>
and <CODE>linuxconf --unsetmod</CODE> command lines.
<P>
<H3>As an independant script, in linuxconf context</H3>
<P>This is almost equivalent to the standalone mode, except that
linuxconf and all its modules are listening. This mode is
necessary if your script uses the virtual registry: Linuxconf
and its modules have to be alived to react properly.
<P>
<BLOCKQUOTE><CODE>
<PRE>
linuxconf --modulemain shellmod --exec script_path \
[--debug] [--perl] script arguments
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="ss2.3">2.3 Layout of a shellmod script</A>
</H2>
<P>A shellmod script will always look like this:
<P>
<BLOCKQUOTE><CODE>
<PRE>
#!/usr/bin/shellmod
. /usr/lib/linuxconf/lib/shellmod-lib.sh
register(){
# Put regmenu and comanager calls here
}
# Put here the various functions referenced above
main(){
# We define a sub-menu or a dialog
}
# The script always end with the dispatch function call. Always
dispatch
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H3>The shellmod-lib.sh function library</H3>
<P>
<H3>The register function</H3>
<P>The register function is required if the script is used
as a Linuxconf module. Linuxconf will call the function expecting
the script to pass back the list of menu and dialog in which
it want to register. Here is an example of a register function
installing two sub-menu and one co-manager.
<P>
<BLOCKQUOTE><CODE>
<PRE>
# Register in the "miscellaneous service" menu
echo regmenu main MENU_MISCSERV \"main menu of the module\"
# Register at the end of the dnsconf menu
echo regmenu function2 dnsconf \"Some title\"
# Register as a co-manager in the user account dialog
echo comanager function-prefix user
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H3>The register function for stand-alone only module</H3>
<P>The register function is not needed for stand-alone module. It is
a good idea to provide a minimal one in case a user try to register
this module in Linuxconf. The following one will make it clear the
script is not intended to be use this way:
<P>
<BLOCKQUOTE><CODE>
<PRE>
register(){
echo error \"This shellmod script can't be use as a module\"
}
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H3>The main function</H3>
<P>If the script is used stand-alone, it requires a function called main.
The shellmod utility will blindly call this function.
It is a good idea to always provide one. In the register function
we often register in a Linuxconf menu the main function. Done this
way, the script provides a consistent interface used either stand-alone
or as a Linuxconf module.
<P>The main function will generally define a menu or a dialog. Note that
the main function is the one which will receive the script arguments.
The arguments will often be used as default values for the dialog fields.
Here is a small example.
<P>
<BLOCKQUOTE><CODE>
<PRE>
main(){
echo DIALOG
echo newf_str path \"Document path\" $1
echo newf_str mail \"Email this document to\" $2
echo newf_str fax \"Fax this document to\" $3
echo edit \"Document manager\" \"Fill this form to send the document\"
dispatch
echo end
if [ "$CODE" = "accept" ] ; then
if [ "$mail" != "" ] ; then
cat $path | mail $mail
fi
if [ "$fax" != "" ] ; then
spoolfax $fax $path
fi
fi
}
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H3>The dispatch function</H3>
<P>A module always ends with a call to the dispatch function. A shellmod
script may be seen as a set of function waiting to be called (A library).
Based on context, Linuxconf (or shellmod for stand-alone scripts) will call
the appropriate one.
<P>Note that the script can perform some initialization before calling
the dispatch function. As explain later, a script may be seen as a small
server which keeps its state between calls to its various functions.
<P>
<H2><A NAME="ss2.4">2.4 How does it works</A>
</H2>
<P>A shellmod script interact with shellmod or Linuxconf by echoing
commands on it standard output. It receives directives by simply
reading its standard input. The dispatch function takes care of
reading and processing (dispatching) the request it receives.
We can think of the script as being in sandwich between two shellmod
process like this
<P>
<BLOCKQUOTE><CODE>
<PRE>
shellmod | script | shellmod
</PRE>
</CODE></BLOCKQUOTE>
<P>Everything echoed by the script is grabbed by shellmod and interpreted
as protocol commands. It is important to redirect the output of sub-command
you are using either to the error channel (<CODE>command >&2</CODE>) or
to /dev/null. Failing to do so will trigger many error messages from
shellmod.
<P>
<HR>
<A HREF="intro-3.html">Next</A>
<A HREF="intro-1.html">Previous</A>
<A HREF="intro.html#toc2">Contents</A>
</BODY>
</HTML>
|
