← Back to branch summary

~galfy/helenos/bird-port-mainline

« back to all changes in this revision

Viewing changes to uspace/app/bdsh/README

  • Committer: Martin Decky
  • Date: 2009-08-04 11:19:19 UTC
  • Revision ID: martin@uranus.dsrg.hide.ms.mff.cuni.cz-20090804111919-evyclddlr3v5lhmp
Initial import

Show diffs side-by-side

added added

removed removed

Lines of Context:
uspace/app/bdsh/README
 
1
BDSH - The Brain Dead Shell | Design Documentation
 
2
--------------------------------------------------
 
3
 
 
4
Overview:
 
5
=========
 
6
 
 
7
BDSH was written as a drop in command line interface for HelenOS to permit
 
8
interactive access to persistent file systems in development. BDSH was
 
9
written from scratch with a very limited userspace standard C library in
 
10
mind. Much like the popular Busybox program, BDSH provides a very limited
 
11
shell with limited common UNIX creature comforts built in.
 
12
 
 
13
Porting Busybox (and by extension ASH) would have taken much longer to
 
14
complete, much less make stable due to stark differences between Linux and
 
15
Spartan with regards to IPC, term I/O and process creation. BDSH was written
 
16
and made stable within the space of less than 30 days.
 
17
 
 
18
BDSH will eventually evolve and be refined into the HelenOS equivalent
 
19
of Busybox. While BDSH is now very intrinsic to HelenOS, its structure and
 
20
use of strictly lower level functions makes it extremely easy to port.
 
21
 
 
22
Design:
 
23
=======
 
24
 
 
25
BDSH is made up of three basic components:
 
26
 
 
27
 1. Main i/o, error handling and task management
 
28
 2. The builtin sub system
 
29
 3. The module sub system
 
30
 
 
31
The main part handles user input, reports errors, spawns external tasks and
 
32
provides a convenient entry point for built-in and modular commands. A simple
 
33
structure, cliuser_t keeps track of the user's vitals, such as their current
 
34
working directory (and eventually uid, home directory, etc if they apply).
 
35
 
 
36
This part defines and exposes all functions that are not intrinsic to a
 
37
certain built in or modular command. For instance: string handlers,
 
38
module/builtin search and launch functions, error handlers and other things
 
39
can be found here.
 
40
 
 
41
Builtin commands are commands that must have access to cliuser_t, which is
 
42
not exposed to modular commands. For instance, the 'cd' command must update
 
43
the current working directory, which is stored in cliuser_t. As such, the
 
44
entry types for builtin commands are slightly different.
 
45
 
 
46
Modular commands do not need anything more than the basic functions that are
 
47
exposed by default. They do not need to modify cliuser_t, they are just self
 
48
contained. A modular command could very easily be made into a stand alone
 
49
program, likewise any stand alone program could easily become a modular
 
50
command.
 
51
 
 
52
Both modular and builtin commands share two things in common. Both must have
 
53
two entry points, one to invoke the command and one to invoke a help display
 
54
for the command. Exec (main()) entry points are int * and are expected to
 
55
return a value. Help entry points are void *, no return value is expected.
 
56
 
 
57
They are typed as such (from cmds.h):
 
58
 
 
59
/* Types for module command entry and help */
 
60
typedef int (* mod_entry_t)(char **);
 
61
typedef void (* mod_help_t)(unsigned int);
 
62
 
 
63
/* Built-in commands need to be able to modify cliuser_t */
 
64
typedef int (* builtin_entry_t)(char **, cliuser_t *);
 
65
typedef void (* builtin_help_t)(unsigned int);
 
66
 
 
67
As you can see, both modular and builtin commands expect an array of
 
68
arguments, however bulitins also expect to be pointed to cliuser_t.
 
69
 
 
70
Both are defined with the same simple structure:
 
71
 
 
72
/* Module structure */
 
73
typedef struct {
 
74
        char *name;         /* Name of the command */
 
75
        char *desc;         /* Description of the command */
 
76
        mod_entry_t entry;  /* Command (exec) entry function */
 
77
        mod_help_t help;    /* Command (help) entry function */
 
78
        int restricted;     /* Restricts to interactive/non-interactive only */
 
79
} module_t;
 
80
 
 
81
NOTE: Builtin commands may grow in this respect, that is why they are
 
82
defined separately.
 
83
 
 
84
Builtins, of course, would use the builtin_entry_t type. The name of the
 
85
command is used to associate user input to a possible entry point. The
 
86
description is a short (40 - 60 chars) summary of what the command does. Both
 
87
entry points are then defined, and the restrict value is used to determine a
 
88
commands availability.
 
89
 
 
90
Restriction levels are easy, a command is either available exclusively within
 
91
interactive mode, exclusively within non-interactive mode or both. If you are
 
92
looking at a prompt, you are in interactive mode. If you issue a command like
 
93
this:
 
94
 
 
95
/sbin/bdsh command [arg1] [arg2]
 
96
 
 
97
... you are in non interactive mode. This is done when you need to force the
 
98
parent shell to be the one who actually handles the command, or ensure that
 
99
/sbin/ls was used in lieu of the built in 'ls' when in non-interactive mode.
 
100
 
 
101
The values are:
 
102
  0 : Unrestricted
 
103
 -1 : Interactive only
 
104
  1 : Non-interactive only
 
105
 
 
106
A script to generate skeletal files for a new command is included, it can be
 
107
found in cmds/mknewcmd. To generate a new modular command named 'foo', which
 
108
should also be reachable by typing 'f00', you would issue this command:
 
109
 
 
110
./mknewcmd -n foo -a f00 -t module
 
111
 
 
112
This generates all needed files and instructs you on how to include your new
 
113
command in the build and make it accessible. By default, the command will be
 
114
unrestricted. Builtin commands can be created by changing 'module' to
 
115
'builtin'
 
116
 
 
117
There are more options to mknewcmd, which allow you to specify the
 
118
description, entry point, help entry point, or restriction. By default, names
 
119
just follow the command such as cmd_foo(), help_cmd_foo(), 'The foo command',
 
120
etc. If you want to see the options and explanations in detail, use
 
121
./mknewcmd --help.
 
122
 
 
123
When working with commands, keep in mind that only the main and help entry
 
124
points need to be exposed. If commands share the same functions, put them
 
125
where they are exposed to all commands, without the potential oops of those
 
126
functions going away if the command is eliminated in favor of a stand alone
 
127
external program.
 
128
 
 
129
The util.c file is a great place to put those types of functions.
 
130
 
 
131
Also, be careful with globals, option structures, etc. The compiler will
 
132
generally tell you if you've made a mistake, however declaring:
 
133
 
 
134
volatile int foo
 
135
 
 
136
... in a command will allow for anything else to pick it up. Sometimes
 
137
this could be desirable .. other times not. When communicating between
 
138
builtins and the main system, try to use cliuser_t. The one exception
 
139
for this is the cli_quit global, since everything may at some point
 
140
need to check it. Modules should only communicate their return value.
 
141
 
 
142
Symbolic constants that everything needs should go in the config.h file,
 
143
however this is not the place to define shared macros.
 
144
 
 
145
Making a program into a module
 
146
==============================
 
147
 
 
148
If you have some neat program that would be useful as a modular command,
 
149
converting it is not very hard. The following steps should get you through
 
150
the process easily (assuming your program is named 'foo'):
 
151
 
 
152
1: Use mknewcmd to generate the skeletal files.
 
153
 
 
154
2: Change your "usage()" command as shown:
 
155
     -- void usage(...)
 
156
     ++ void help_cmd_foo(unsigned int level)
 
157
 
 
158
     'level' is either 0 or 1, indicating the level of help requested.
 
159
     If the help / usage function currently exits based on how it is
 
160
     called, you'll need to change it.
 
161
 
 
162
3: Change the programs "main()" as shown:
 
163
     -- int main(int argc, char **argv)
 
164
     ++ int cmd_foo(char **argv)
 
165
     -- return 1;
 
166
     ++ return CMD_FAILURE;
 
167
     -- return 0;
 
168
     ++ return CMD_SUCCESS;
 
169
 
 
170
     NOTE: If main is void, you'll need to change it and ensure that its
 
171
     expecting an array of arguments, even if they'll never be read or
 
172
     used. I.e.:
 
173
 
 
174
     -- void main(void)
 
175
     ++ int cmd_foo(char **argv)
 
176
 
 
177
4: Don't expose more than the entry and help points:
 
178
     -- void my_function(int n)
 
179
     ++ static void my_function(int n)
 
180
 
 
181
5: Copy/paste to the stub generated by mknewcmd then add your files to the
 
182
   Makefile. Be sure to add any directories that you made to the SUBDIRS so
 
183
   that a 'make clean' will clean them.
 
184
 
 
185
Provided that all functions that your calling are available in the
 
186
userspace C library, your program should compile just fine and appear
 
187
as a modular command.
 
188
 
 
189
Overcoming userspace libc obstacles
 
190
===================================
 
191
 
 
192
A quick glance through the util.c file will reveal functions like
 
193
cli_strdup(), cli_strtok(), cli_strtok_r() and more. Those are functions
 
194
that were missing from userspace libc when BDSH was born. Later, after
 
195
porting what was needed from FBSD/NBSD, the real functions appeared in
 
196
the userspace libc after being tested in their cli_* implementations.
 
197
 
 
198
Those functions remain because they guarantee that bdsh will work even
 
199
on systems that lack them. Additionally, more BDSH specific stuff can
 
200
go into them, such as error handling and reporting when malloc() fails.
 
201
 
 
202
You will also notice that FILE, fopen() (and all friends), ato*() and
 
203
other common things might be missing. The HelenOS userspace C library is
 
204
still very young, you are sure to run into something that you want/need
 
205
which is missing.
 
206
 
 
207
When that happens, you have three options:
 
208
 
 
209
1 - Implement it internally in util.c , when its tested and stable send a
 
210
patch to HelenOS asking for your function to be included in libc. This is
 
211
the best option, as you not only improve BDSH .. but HelenOS as a whole.
 
212
 
 
213
2 - Work around it. Not everyone can implement / port fopen() and all of
 
214
its friends. Make open(), read(), write() (etc) work if at all possible.
 
215
 
 
216
3 - Send an e-mail to the HelenOS development mailing list. Explain why you
 
217
need the function and what its absence is holding up.
 
218
 
 
219
If what you need is part of a library that is typically a shared object, try
 
220
to implement a 'mini' version of it. Currently, all userspace applications
 
221
are statically linked. Giving up creature comforts for size while avoiding
 
222
temporary 'band aids' is never frowned upon.
 
223
 
 
224
Most of all, don't get discouraged .. ask for some help prior to giving up
 
225
if you just can't accomplish something with the limited means provided.
 
226
 
 
227
Contributing
 
228
============
 
229
 
 
230
I will take any well written patch that sanely improves or expands BDSH. Send
 
231
me a patch against the trunk revision, or, if you like a Mercurial repository
 
232
is also maintained at http://echoreply.us/hg/bdsh.hg and kept in sync with
 
233
the trunk.
 
234
 
 
235
Please be sure to follow the simple coding standards outlined at
 
236
http://www.helenos.eu/cstyle (mostly just regarding formatting), test your
 
237
changes and make sure your patch applies cleanly against the latest revision.
 
238
 
 
239
All patches submitted must be your original code, or a derivative work of
 
240
something licensed under the same 3 clause BSD license as BDSH. See LICENSE
 
241
for more information.
 
242
 
 
243
When sending patches, you agree that your work will be published under the
 
244
same 3 clause BSD license as BDSH itself. Failure to ensure that anything
 
245
you used is not under the same or less restrictive license could cause major
 
246
issues for BDSH in the future .. please be sure. Also, please don't forget
 
247
to add yourself in the AUTHORS file, as I am horrible about keeping such
 
248
things up to date.
 
249
 
 
250
 
 
251
 
 
252