1 |
commit: 0678580564dcf6aa8e2587d3b04d62544265ca74 |
2 |
Author: André Erdmann <dywi <AT> mailerd <DOT> de> |
3 |
AuthorDate: Wed Jun 26 17:28:39 2013 +0000 |
4 |
Commit: André Erdmann <dywi <AT> mailerd <DOT> de> |
5 |
CommitDate: Wed Jun 26 17:28:39 2013 +0000 |
6 |
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/R_overlay.git;a=commit;h=06785805 |
7 |
|
8 |
doc/rst: "run hooks", "distmap" |
9 |
|
10 |
--- |
11 |
doc/rst/usage.rst | 643 ++++++++++++++++++++++++++++++++---------------------- |
12 |
1 file changed, 383 insertions(+), 260 deletions(-) |
13 |
|
14 |
diff --git a/doc/rst/usage.rst b/doc/rst/usage.rst |
15 |
index 078a7ac..2daedce 100644 |
16 |
--- a/doc/rst/usage.rst |
17 |
+++ b/doc/rst/usage.rst |
18 |
@@ -1010,6 +1010,22 @@ A local directory will never be modified. |
19 |
consider using one of the **websync** repo types, websync_repo_ and |
20 |
websync_pkglist_. |
21 |
|
22 |
+--------- |
23 |
+ distmap |
24 |
+--------- |
25 |
+ |
26 |
+*roverlay* uses a text file to store information about files in the package |
27 |
+mirror directory (OVERLAY_DISTDIR_ROOT_). This is necessary for comparing |
28 |
+package files from repos with files for which an ebuild has already been |
29 |
+created (in previous runs). |
30 |
+ |
31 |
+With the help of the *distmap file*, *roverlay* is able to determine whether |
32 |
+upstream has changed a package file silently and creates a revision-bumped |
33 |
+ebuild for the *new* package file. |
34 |
+ |
35 |
+The *distmap file* can optionally be compressed (bzip2 or gzip), which |
36 |
+reduces its size considerably. |
37 |
+ |
38 |
|
39 |
===================== |
40 |
Additions Directory |
41 |
@@ -1790,6 +1806,354 @@ Moving such packages to a "R-package" sub directory would be possible, too: |
42 |
END; |
43 |
|
44 |
|
45 |
+============= |
46 |
+ Event Hooks |
47 |
+============= |
48 |
+ |
49 |
+*roverlay* is able to call a script when certain events occur, e.g. after |
50 |
+successful overlay creation, which can be used to perform additional actions |
51 |
+without touching *roverlay's* source code. |
52 |
+ |
53 |
+To realize this, *roverlay* determines whether a given event is permitted |
54 |
+(`event policy`_) and, if so, creates a `hook environment`_ and runs the |
55 |
+script. Additionally, shell scripts can load *roverlay's* *$FUNCTIONS* file, |
56 |
+which provides extra functionality. |
57 |
+ |
58 |
+.. Note:: |
59 |
+ |
60 |
+ *roverlay* waits until the script terminates and thus possibly waits |
61 |
+ forever. |
62 |
+ |
63 |
+ |
64 |
+---------------------- |
65 |
+ Default event script |
66 |
+---------------------- |
67 |
+ |
68 |
+The default event script (``mux.sh``) loads *$FUNCTIONS* and then runs the |
69 |
+following script files (by sourcing them), in order: |
70 |
+ |
71 |
+#. all files from ADDITIONS_DIR_/hooks/<event> that end with *.sh* |
72 |
+ (``<ADDITIONS_DIR>/hooks/<event>/*.sh``) |
73 |
+#. all files ADDITIONS_DIR_/hooks that end with *.<event>* |
74 |
+ (``<ADDITIONS_DIR>/hooks/*.<event>``) |
75 |
+ |
76 |
+So, there are two naming schemes for *hook scripts*. |
77 |
+Either one is acceptable, but it is advised to stay consistent. |
78 |
+Having the same script at both locations results in executing it twice. |
79 |
+ |
80 |
+.. Note:: |
81 |
+ |
82 |
+ The default event script enables *nounset* behavior, which causes the |
83 |
+ shell command interpreter to exit abnormally if an unset variable is |
84 |
+ accessed. |
85 |
+ |
86 |
+ |
87 |
+++++++++++++++++++++++++++ |
88 |
+ Activating a hook script |
89 |
+++++++++++++++++++++++++++ |
90 |
+ |
91 |
+Activating a hook script can be done by symlinking it: |
92 |
+ |
93 |
+.. code-block:: text |
94 |
+ |
95 |
+ ln -s <real script> ${ADDITIONS_DIR}/hooks/<event>/<name>.sh |
96 |
+ # or |
97 |
+ ln -s <real script> ${ADDITIONS_DIR}/hooks/<name>.<event> |
98 |
+ |
99 |
+ |
100 |
+++++++++++++++++++++++++++ |
101 |
+ Adding a new hook script |
102 |
+++++++++++++++++++++++++++ |
103 |
+ |
104 |
+As hinted before, *hook scripts* are simple shell scripts. The following |
105 |
+template gives an idea of how to write them: |
106 |
+ |
107 |
+.. code-block:: sh |
108 |
+ |
109 |
+ #!/bin/sh |
110 |
+ #set -u |
111 |
+ |
112 |
+ # load essential functions |
113 |
+ # (not necessary when using the default event script) |
114 |
+ . "${FUNCTIONS?}" || exit |
115 |
+ |
116 |
+ ## load additional function files, if any |
117 |
+ #$lf <name(s)> |
118 |
+ |
119 |
+ # script body |
120 |
+ # |
121 |
+ # when redirecting output to $DEVNULL, use ">>" instead of ">" as |
122 |
+ # $DEVNULL could be a file |
123 |
+ #ls >>${DEVNULL} |
124 |
+ # |
125 |
+ # ... |
126 |
+ |
127 |
+ |
128 |
+ # the script must not exit if everything went well (return is ok) |
129 |
+ return 0 |
130 |
+ |
131 |
+ |
132 |
+-------------- |
133 |
+ Event Policy |
134 |
+-------------- |
135 |
+ |
136 |
+The *event policy* controls whether a certain event actually triggers a script |
137 |
+call or not. |
138 |
+It is constructed by parsing the EVENT_HOOK_RESTRICT_ config option: |
139 |
+ |
140 |
+* a word prefixed by ``-`` means *deny specific event* (-> blacklist) |
141 |
+* the asterisk char ``*`` (or ``+*``) sets the policy to |
142 |
+ *allow unless denied* (blacklist) or *allow all* |
143 |
+* a word prefixed by ``+`` or without a prefix char means |
144 |
+ *allow specific event* (-> whitelist) |
145 |
+* the asterisk char with ``-`` as prefix (``-*``) sets the policy to |
146 |
+ *deny unless allowed* (whitelist) or *deny all* |
147 |
+ |
148 |
+ |
149 |
+The policy defaults to *allow all* if ``EVENT_HOOK_RESTRICT`` is not set in |
150 |
+the config file. An empty string sets the policy to *deny all*. |
151 |
+ |
152 |
+ |
153 |
+------------------ |
154 |
+ Hook Environment |
155 |
+------------------ |
156 |
+ |
157 |
+.. table:: environment variables provided by *roverlay* |
158 |
+ |
159 |
+ +----------------+-------------------+-----------------------------------------+ |
160 |
+ | variable | source | notes / description | |
161 |
+ +================+===================+=========================================+ |
162 |
+ | PATH | os.environ | | |
163 |
+ +----------------+-------------------+-----------------------------------------+ |
164 |
+ | LOGNAME | os.environ | | |
165 |
+ +----------------+-------------------+-----------------------------------------+ |
166 |
+ | SHLVL | os.environ | | |
167 |
+ +----------------+-------------------+-----------------------------------------+ |
168 |
+ | TERM | os.environ | | |
169 |
+ +----------------+-------------------+-----------------------------------------+ |
170 |
+ | HOME | os.environ | | |
171 |
+ +----------------+-------------------+-----------------------------------------+ |
172 |
+ | ROVERLAY_PHASE | event | event that caused the script to run | |
173 |
+ +----------------+-------------------+-----------------------------------------+ |
174 |
+ | OVERLAY | config | overlay directory (`OVERLAY_DIR`_), | |
175 |
+ +----------------+-------------------+ initial working directory | |
176 |
+ | S | *$OVERLAY* | | |
177 |
+ +----------------+-------------------+ | |
178 |
+ | PWD | *$OVERLAY* | | |
179 |
+ +----------------+-------------------+-----------------------------------------+ |
180 |
+ | DISTROOT | config | package mirror directory | |
181 |
+ | | | (`OVERLAY_DISTDIR_ROOT`_) | |
182 |
+ +----------------+-------------------+-----------------------------------------+ |
183 |
+ | TMPDIR | os.environ, | directory for temporary files | |
184 |
+ | | *fallback* | | |
185 |
+ +----------------+-------------------+ | |
186 |
+ | T | *$TMPDIR* | | |
187 |
+ +----------------+-------------------+-----------------------------------------+ |
188 |
+ | ADDITIONS_DIR | config | directory with supplementary files | |
189 |
+ | | | (`OVERLAY_ADDITIONS_DIR`_) | |
190 |
+ +----------------+-------------------+ | |
191 |
+ | FILESDIR | *$ADDITIONS_DIR* | | |
192 |
+ +----------------+-------------------+-----------------------------------------+ |
193 |
+ | SHLIB | *$ADDITIONS_DIR*, | A list of directories with shell | |
194 |
+ | | *installed?* | function files | |
195 |
+ | | | (optional, only set if any dir exists) | |
196 |
+ +----------------+-------------------+-----------------------------------------+ |
197 |
+ | FUNCTIONS | *$ADDITIONS_DIR*, | file with essential shell functions | |
198 |
+ | | *installed?* | (optional, only set if it exists) | |
199 |
+ +----------------+-------------------+-----------------------------------------+ |
200 |
+ | DEBUG | log level | *shbool* (``y`` or ``n``) that | |
201 |
+ | | | indicates whether debug messages should | |
202 |
+ | | | be printed | |
203 |
+ +----------------+-------------------+-----------------------------------------+ |
204 |
+ | VERBOSE | log level | *shbool* | |
205 |
+ +----------------+-------------------+-----------------------------------------+ |
206 |
+ | QUIET | log level | *shbool* that indicates whether scripts | |
207 |
+ | | | should be quiet | |
208 |
+ +----------------+-------------------+-----------------------------------------+ |
209 |
+ | NO_COLOR | *n/a* | *shbool*. Always set to *y* since | |
210 |
+ | | | colored output should not be produced | |
211 |
+ +----------------+-------------------+-----------------------------------------+ |
212 |
+ | NOSYNC | config | *shbool* that indicates whether data | |
213 |
+ | | | transfers from/to remote machines is | |
214 |
+ | | | allowed (NOSYNC_) | |
215 |
+ +----------------+-------------------+-----------------------------------------+ |
216 |
+ | EBUILD | config | the *ebuild* executable | |
217 |
+ +----------------+-------------------+-----------------------------------------+ |
218 |
+ | GIT_EDITOR | *n/a* | set to */bin/false* | |
219 |
+ +----------------+-------------------+ | |
220 |
+ | GIT_ASKPASS | *n/a* | | |
221 |
+ +----------------+-------------------+-----------------------------------------+ |
222 |
+ |
223 |
+ |
224 |
+The default *essential shell functions* file (*$FUNCTIONS*) makes, |
225 |
+when included in the hook script, most of the enviroment variables readonly. |
226 |
+ |
227 |
+ |
228 |
+.. table:: variables provided by *$FUNCTIONS* |
229 |
+ |
230 |
+ +-----------------+-------------------------------------------------------+ |
231 |
+ | variable | description | |
232 |
+ +=================+=======================================================+ |
233 |
+ | IFS_DEFAULT | default *internal field separator* | |
234 |
+ +-----------------+-------------------------------------------------------+ |
235 |
+ | IFS_NEWLINE | *IFS* for iterating over text lines | |
236 |
+ +-----------------+-------------------------------------------------------+ |
237 |
+ | DEVNULL | */dev/null* target (could also be a file) | |
238 |
+ +-----------------+-------------------------------------------------------+ |
239 |
+ | EX_ERR | default error exit code | |
240 |
+ +-----------------+-------------------------------------------------------+ |
241 |
+ | EX_ARG_ERR | default exit code for arg errors | |
242 |
+ +-----------------+-------------------------------------------------------+ |
243 |
+ | SCRIPT_FILENAME | file name of the hook script | |
244 |
+ +-----------------+-------------------------------------------------------+ |
245 |
+ | SCRIPT_NAME | name of the hook script (without file extension) | |
246 |
+ +-----------------+-------------------------------------------------------+ |
247 |
+ | lf | reference to a function that loads additional shell | |
248 |
+ | | function files | |
249 |
+ +-----------------+-------------------------------------------------------+ |
250 |
+ |
251 |
+ |
252 |
+*$FUNCTIONS* also provides a number of shell functions: |
253 |
+ |
254 |
+.. code-block:: sh |
255 |
+ |
256 |
+ # --- message --- |
257 |
+ # |
258 |
+ # void veinfo ( message ) |
259 |
+ # Prints a message to stdout if $DEBUG is set to 'y'. |
260 |
+ # |
261 |
+ # void einfo ( message ) |
262 |
+ # Prints a message to stdout if $VERBOSE is set to 'y'. |
263 |
+ # |
264 |
+ # void ewarn ( message ) |
265 |
+ # Prints a message to stderr unless $QUIET is set to 'y'. |
266 |
+ # |
267 |
+ # void eerror ( message ) |
268 |
+ # Prints a message to stderr. |
269 |
+ # |
270 |
+ # |
271 |
+ # --- core --- |
272 |
+ # |
273 |
+ # @noreturn die ( [message], [exit_code] ), raises exit() |
274 |
+ # Lets the script die with the given message/exit code. |
275 |
+ # |
276 |
+ # @noreturn OUT_OF_BOUNDS(), raises die() |
277 |
+ # Lets the script die due to insufficient arg count. |
278 |
+ # |
279 |
+ # int run_command ( *cmdv ) |
280 |
+ # Logs a command and runs it afterwards. |
281 |
+ # |
282 |
+ # int run_command_logged ( *cmdv ) |
283 |
+ # Logs a command, runs it and logs the result. |
284 |
+ # |
285 |
+ # void autodie ( *cmdv ), raises die() |
286 |
+ # Runs a command. Lets the script die if the command fails. |
287 |
+ # |
288 |
+ # |
289 |
+ # void load_functions ( *filenames, **SHLIB ), raises die() |
290 |
+ # Loads additional shell functions file(s) from $SHLIB. |
291 |
+ # (Referenced by $lf.) |
292 |
+ # |
293 |
+ # void dont_run_as_root(), raises die() |
294 |
+ # Lets the script die if it is run as root. |
295 |
+ # |
296 |
+ # int list_has ( word, *list_items ) |
297 |
+ # Returns 0 if $word is in the given list, else 1. |
298 |
+ # |
299 |
+ # int qwhich ( *command ) |
300 |
+ # Returns 0 if all listed commands are found by "which", else 1. |
301 |
+ # |
302 |
+ # |
303 |
+ # --- fs --- |
304 |
+ # |
305 |
+ # int dodir ( *dir ) |
306 |
+ # Ensures that zero or more directories exist by creating them if |
307 |
+ # necessary. Returns the number of directories that could not be created. |
308 |
+ # |
309 |
+ # |
310 |
+ # --- str --- |
311 |
+ # |
312 |
+ # int yesno ( word, **YESNO_YES=0, **YESNO_NO=1, **YESNO_EMPTY=2 ) |
313 |
+ # Returns $YESNO_YES if $word means "yes", $YESNO_EMPTY if $word is empty |
314 |
+ # and $YESNO_NO otherwise (if $word probably means "no"). |
315 |
+ # |
316 |
+ # ~int str_trim ( *args ) |
317 |
+ # Removes whitespace at the beginning and end of a string and replaces |
318 |
+ # any whitespace sequence within the string with a single space char. |
319 |
+ # Passes the return value of the underlying sed command. |
320 |
+ # |
321 |
+ # ~int str_upper ( *args ) |
322 |
+ # Echoes the uppercase variant of stdin or *args. |
323 |
+ # Passes tr's return value. |
324 |
+ # |
325 |
+ # ~int str_lower ( *args ) |
326 |
+ # Echoes the lowercase variant of stdin or *args. |
327 |
+ # Passes tr's return value. |
328 |
+ # |
329 |
+ # ~int str_field ( fieldspec, *args, **FIELD_SEPARATOR=' ' ) |
330 |
+ # Echoes the requested fields of stdin or *args. |
331 |
+ # Passes cut's return value. |
332 |
+ # |
333 |
+ # |
334 |
+ # --- int --- |
335 |
+ # |
336 |
+ # int is_int ( word ) |
337 |
+ # Returns 0 if $word is an integer, else 1. |
338 |
+ # |
339 |
+ # int is_natural ( word ) |
340 |
+ # Returns 0 if $word is an integer >= 0, else 1. |
341 |
+ # |
342 |
+ # int is_positive ( word ) |
343 |
+ # Returns 0 if $word is an integer >= 1, else 1. |
344 |
+ # |
345 |
+ # int is_negative ( word ) |
346 |
+ # Returns 0 if $word is an integer < 0, else 1. |
347 |
+ # |
348 |
+ |
349 |
+ |
350 |
+------------------------ |
351 |
+ Adding a function file |
352 |
+------------------------ |
353 |
+ |
354 |
+Function files are shell script files that provide functions and variables. |
355 |
+They should, however, not execute any code directly. |
356 |
+ |
357 |
+The template below illustrates how to write function files: |
358 |
+ |
359 |
+.. code-block:: sh |
360 |
+ |
361 |
+ # protect against repeated inclusion of this file |
362 |
+ # (replace <name> with a unique identifier) |
363 |
+ if [ -z "${__HAVE_<name>__-}" ]; then |
364 |
+ readonly __HAVE_<name>__=y |
365 |
+ |
366 |
+ # function file body |
367 |
+ # ... |
368 |
+ |
369 |
+ fi |
370 |
+ |
371 |
+Shell function files should be put into ``<ADDITIONS_DIR>/shlib``. |
372 |
+ |
373 |
+--------------------- |
374 |
+ Adding a hook event |
375 |
+--------------------- |
376 |
+ |
377 |
+Adding a new event has to be done in *roverlay's* source code and is a rather |
378 |
+trivial task. The ``roverlay.hook`` module implements a function for running |
379 |
+the event script: |
380 |
+ |
381 |
+.. code-block:: python |
382 |
+ |
383 |
+ # import hook module |
384 |
+ import roverlay.hook |
385 |
+ |
386 |
+ # ... |
387 |
+ # then, somewhere in the code |
388 |
+ roverlay.hook.run ( "<event>" ) |
389 |
+ # ... |
390 |
+ roverlay.hook.run ( "<another event>" ) |
391 |
+ |
392 |
+ |
393 |
========================= |
394 |
Configuration Reference |
395 |
========================= |
396 |
@@ -1936,6 +2300,11 @@ DISTDIR_STRATEGY |
397 |
DISTDIR_VERIFY |
398 |
Alias to OVERLAY_DISTDIR_VERIFY_. |
399 |
|
400 |
+.. _DISTMAP_COMPRESSION: |
401 |
+ |
402 |
+DISTMAP_COMPRESSION |
403 |
+ Alias to OVERLAY_DISTMAP_COMPRESSION_. |
404 |
+ |
405 |
.. _DISTMAP_FILE: |
406 |
|
407 |
DISTMAP_FILE |
408 |
@@ -2051,6 +2420,13 @@ OVERLAY_DISTDIR_VERIFY |
409 |
|
410 |
Defaults to *no* as the verification is normally not needed. |
411 |
|
412 |
+.. _OVERLAY_DISTMAP_COMPRESSION: |
413 |
+ |
414 |
+OVERLAY_DISTMAP_COMPRESSION |
415 |
+ Compression format for the distmap file. Choices are none, gzip/gz and |
416 |
+ bzip2/bz2. |
417 |
+ |
418 |
+ Defaults to bzip2. |
419 |
|
420 |
.. _OVERLAY_DISTMAP_FILE: |
421 |
|
422 |
@@ -2212,9 +2588,10 @@ USE_EXPAND_RENAME |
423 |
.. _EVENT_HOOK: |
424 |
|
425 |
EVENT_HOOK |
426 |
- A script that is called for handling *events* (see Hooks_). |
427 |
+ A script that is called for handling *events* (see `Event Hooks`_). |
428 |
|
429 |
- Defaults to ADDITIONS_DIR_/hooks/mux.sh. |
430 |
+ Defaults to <libexec dir>/hooks/mux.sh if roverlay has been installed |
431 |
+ and ADDITIONS_DIR_/hooks/mux.sh otherwise. |
432 |
|
433 |
.. _EVENT_HOOK_RESTRICT: |
434 |
|
435 |
@@ -2226,6 +2603,10 @@ EVENT_HOOK_RESTRICT |
436 |
|
437 |
Defaults to <not set>, which is equivalent to *deny all*. |
438 |
|
439 |
+ ``EVENT_HOOK_RESTRICT="overlay_success"`` would allow the ``overlay_success`` |
440 |
+ event only, whereas ``EVENT_HOOK_RESTRICT="* -overlay_success"`` would |
441 |
+ allow any event except for ``overlay_success``. Also see `event policy`_. |
442 |
+ |
443 |
.. _FILTER_SHELL_ENV: |
444 |
|
445 |
FILTER_SHELL_ENV |
446 |
@@ -3242,261 +3623,3 @@ Its mode of operation of operation is best described in pseudo-code: |
447 |
|
448 |
The dependency resolver can be **run as thread**, in which case the while loop |
449 |
becomes "loop until resolver closes". |
450 |
- |
451 |
- |
452 |
-======= |
453 |
- undef |
454 |
-======= |
455 |
- |
456 |
-<<TODO; this section has to merged/moved>> |
457 |
- |
458 |
---------- |
459 |
- distmap |
460 |
---------- |
461 |
- |
462 |
-The distmap is a file that stores information about the files in the package |
463 |
-mirror directory (`OVERLAY_DISTDIR_ROOT`_). |
464 |
-<<TODO>> |
465 |
- |
466 |
- |
467 |
-------- |
468 |
- hooks |
469 |
-------- |
470 |
- |
471 |
-*roverlay* calls a script when certain events occur, e.g. after successful |
472 |
-overlay creation. |
473 |
- |
474 |
-<<TODO>> |
475 |
- |
476 |
-* real work is offloaded to the called script |
477 |
-* roverlay provides some env vars |
478 |
-* roverlay provides a *$FUNCTIONS* file and a way to load other function files |
479 |
-* ``EVENT_HOOK_RESTRICT="this -not_that *"`` |
480 |
- |
481 |
-<<^^TODO>> |
482 |
- |
483 |
-.. Note:: |
484 |
- |
485 |
- *roverlay* waits until the script terminates. |
486 |
- |
487 |
- |
488 |
-++++++++++++++++++ |
489 |
- Hook environment |
490 |
-++++++++++++++++++ |
491 |
- |
492 |
-.. table:: environment variables provided by *roverlay* |
493 |
- |
494 |
- +----------------+------------------+-----------------------------------------+ |
495 |
- | variable | source | notes / description | |
496 |
- +================+==================+=========================================+ |
497 |
- | PATH | os.environ | | |
498 |
- +----------------+------------------+-----------------------------------------+ |
499 |
- | LOGNAME | os.environ | | |
500 |
- +----------------+------------------+-----------------------------------------+ |
501 |
- | SHLVL | os.environ | | |
502 |
- +----------------+------------------+-----------------------------------------+ |
503 |
- | TERM | os.environ | | |
504 |
- +----------------+------------------+-----------------------------------------+ |
505 |
- | HOME | os.environ | | |
506 |
- +----------------+------------------+-----------------------------------------+ |
507 |
- | ROVERLAY_PHASE | event | event that caused the script to run | |
508 |
- +----------------+------------------+-----------------------------------------+ |
509 |
- | OVERLAY | config | overlay directory (`OVERLAY_DIR`_), | |
510 |
- +----------------+------------------+ initial working directory | |
511 |
- | S | *$OVERLAY* | | |
512 |
- +----------------+------------------+ | |
513 |
- | PWD | *$OVERLAY* | | |
514 |
- +----------------+------------------+-----------------------------------------+ |
515 |
- | DISTROOT | config | package mirror directory | |
516 |
- | | | (`OVERLAY_DISTDIR_ROOT`_) | |
517 |
- +----------------+------------------+-----------------------------------------+ |
518 |
- | TMPDIR | os.environ, | directory for temporary files | |
519 |
- | | *fallback* | | |
520 |
- +----------------+------------------+ | |
521 |
- | T | *$TMPDIR* | | |
522 |
- +----------------+------------------+-----------------------------------------+ |
523 |
- | ADDITIONS_DIR | config | directory with supplementary files | |
524 |
- | | | (`OVERLAY_ADDITIONS_DIR`_) | |
525 |
- +----------------+------------------+ | |
526 |
- | FILESDIR | *$ADDITIONS_DIR* | | |
527 |
- +----------------+------------------+-----------------------------------------+ |
528 |
- | SHLIB | *$ADDITIONS_DIR* | directory with shell function files | |
529 |
- | | | (optional, only set if it exists) | |
530 |
- +----------------+------------------+-----------------------------------------+ |
531 |
- | FUNCTIONS | *$ADDITIONS_DIR* | file with essential shell functions | |
532 |
- | | | (optional, only set if it exists) | |
533 |
- +----------------+------------------+-----------------------------------------+ |
534 |
- | DEBUG | log level | *shbool* (``y`` or ``n``) that | |
535 |
- | | | indicates whether debug messages should | |
536 |
- | | | be printed | |
537 |
- +----------------+------------------+-----------------------------------------+ |
538 |
- | VERBOSE | log level | *shbool* | |
539 |
- +----------------+------------------+-----------------------------------------+ |
540 |
- | QUIET | log level | *shbool* that indicates whether scripts | |
541 |
- | | | should be quiet | |
542 |
- +----------------+------------------+-----------------------------------------+ |
543 |
- | NO_COLOR | *n/a* | *shbool*. Always set to *y* since | |
544 |
- | | | colored output should not be produced | |
545 |
- +----------------+------------------+-----------------------------------------+ |
546 |
- | NOSYNC | config | *shbool* that indicates whether data | |
547 |
- | | | transfers from/to remote machines is | |
548 |
- | | | allowed (NOSYNC_) | |
549 |
- +----------------+------------------+-----------------------------------------+ |
550 |
- | EBUILD | config | the *ebuild* executable | |
551 |
- +----------------+------------------+-----------------------------------------+ |
552 |
- | GIT_EDITOR | *n/a* | set to */bin/false* | |
553 |
- +----------------+------------------+ | |
554 |
- | GIT_ASKPASS | *n/a* | | |
555 |
- +----------------+------------------+-----------------------------------------+ |
556 |
- |
557 |
- |
558 |
-The default *essential shell functions* file (*$FUNCTIONS*) makes, |
559 |
-when included in the hook script, most of the enviroment variables readonly. |
560 |
- |
561 |
- |
562 |
-.. table:: variables provided by *$FUNCTIONS* |
563 |
- |
564 |
- +-----------------+-------------------------------------------------------+ |
565 |
- | variable | description | |
566 |
- +=================+=======================================================+ |
567 |
- | IFS_DEFAULT | default *internal field separator* | |
568 |
- +-----------------+-------------------------------------------------------+ |
569 |
- | IFS_NEWLINE | *IFS* for iterating over text lines | |
570 |
- +-----------------+-------------------------------------------------------+ |
571 |
- | DEVNULL | */dev/null* target (could also be a file) | |
572 |
- +-----------------+-------------------------------------------------------+ |
573 |
- | EX_ERR | default error exit code | |
574 |
- +-----------------+-------------------------------------------------------+ |
575 |
- | EX_ARG_ERR | default exit code for arg errors | |
576 |
- +-----------------+-------------------------------------------------------+ |
577 |
- | SCRIPT_FILENAME | file name of the hook script | |
578 |
- +-----------------+-------------------------------------------------------+ |
579 |
- | SCRIPT_NAME | name of the hook script (without file extension) | |
580 |
- +-----------------+-------------------------------------------------------+ |
581 |
- | lf | reference to a function that loads additional shell | |
582 |
- | | function files | |
583 |
- +-----------------+-------------------------------------------------------+ |
584 |
- |
585 |
- |
586 |
-*$FUNCTIONS* also provides a number of shell functions: |
587 |
- |
588 |
-.. code-block:: sh |
589 |
- |
590 |
- # --- message --- |
591 |
- # |
592 |
- # void veinfo ( message ) |
593 |
- # Prints a message to stdout if $DEBUG is set to 'y'. |
594 |
- # |
595 |
- # void einfo ( message ) |
596 |
- # Prints a message to stdout if $VERBOSE is set to 'y'. |
597 |
- # |
598 |
- # void ewarn ( message ) |
599 |
- # Prints a message to stderr unless $QUIET is set to 'y'. |
600 |
- # |
601 |
- # void eerror ( message ) |
602 |
- # Prints a message to stderr. |
603 |
- # |
604 |
- # |
605 |
- # --- core --- |
606 |
- # |
607 |
- # @noreturn die ( [message], [exit_code] ), raises exit() |
608 |
- # Lets the script die with the given message/exit code. |
609 |
- # |
610 |
- # @noreturn OUT_OF_BOUNDS(), raises die() |
611 |
- # Lets the script die due to insufficient arg count. |
612 |
- # |
613 |
- # int run_command ( *cmdv ) |
614 |
- # Logs a command and runs it afterwards. |
615 |
- # |
616 |
- # int run_command_logged ( *cmdv ) |
617 |
- # Logs a command, runs it and logs the result. |
618 |
- # |
619 |
- # void autodie ( *cmdv ), raises die() |
620 |
- # Runs a command. Lets the script die if the command fails. |
621 |
- # |
622 |
- # |
623 |
- # void load_functions ( *filenames, **SHLIB ), raises die() |
624 |
- # Loads additional shell functions file(s) from $SHLIB. |
625 |
- # (Referenced by $lf.) |
626 |
- # |
627 |
- # void dont_run_as_root(), raises die() |
628 |
- # Lets the script die if it is run as root. |
629 |
- # |
630 |
- # int list_has ( word, *list_items ) |
631 |
- # Returns 0 if $word is in the given list. |
632 |
- # |
633 |
- # int qwhich ( *command ) |
634 |
- # Returns 0 if all listed commands are found by "which". |
635 |
- # |
636 |
- # |
637 |
- # --- fs --- |
638 |
- # |
639 |
- # int dodir ( *dir ) |
640 |
- # Ensures that zero or more directories exist by creating them if |
641 |
- # necessary. Returns the number of directories that could not be created. |
642 |
- # |
643 |
- # |
644 |
- # --- str --- |
645 |
- # |
646 |
- # int yesno ( word, **YESNO_YES=0, **YESNO_NO=1, **YESNO_EMPTY=2 ) |
647 |
- # Returns $YESNO_YES if $word means "yes", $YESNO_EMPTY if $word is empty |
648 |
- # and $YESNO_NO otherwise (if $word probably means "no"). |
649 |
- # |
650 |
- # ~int str_trim ( *args ) |
651 |
- # Removes whitespace at the beginning and end of a string and replaces |
652 |
- # any whitespace sequence within the string with a single space char. |
653 |
- # Passes the return value of the underlying sed command. |
654 |
- # |
655 |
- # ~int str_upper ( *args ) |
656 |
- # Echoes the uppercase variant of stdin or *args. |
657 |
- # Passes tr's return value. |
658 |
- # |
659 |
- # ~int str_lower ( *args ) |
660 |
- # Echoes the lowercase variant of stdin or *args. |
661 |
- # Passes tr's return value. |
662 |
- # |
663 |
- # ~int str_field ( fieldspec, *args, **FIELD_SEPARATOR=' ' ) |
664 |
- # Echoes the requested fields of stdin or *args. |
665 |
- # Passes cut's return value. |
666 |
- # |
667 |
- # |
668 |
- # --- int --- |
669 |
- # |
670 |
- # int is_int ( word ) |
671 |
- # Returns 0 if $word is an integer, else 1. |
672 |
- # |
673 |
- # int is_natural ( word ) |
674 |
- # Returns 0 if $word is an integer >= 0, else 1. |
675 |
- # |
676 |
- # int is_positive ( word ) |
677 |
- # Returns 0 if $word is an integer >= 1, else 1. |
678 |
- # |
679 |
- # int is_negative ( word ) |
680 |
- # Returns 0 if $word is an integer < 0, else 1. |
681 |
- # |
682 |
- |
683 |
- |
684 |
-+++++++++++++++++++++ |
685 |
- Adding a hook event |
686 |
-+++++++++++++++++++++ |
687 |
- |
688 |
-in roverlay |
689 |
- |
690 |
-.. code-block:: python |
691 |
- |
692 |
- # import hook module |
693 |
- import roverlay.hook |
694 |
- |
695 |
- # ... |
696 |
- # then: |
697 |
- roverlay.hook.run ( "<event>" ) |
698 |
- # ... |
699 |
- roverlay.hook.run ( "<another event>" ) |
700 |
- |
701 |
- |
702 |
-in additions dir (assuming that mux.sh is used) |
703 |
- |
704 |
-.. code-block:: text |
705 |
- |
706 |
- <somehow create> ${ADDITIONS_DIR}/<hook>.<event> |
707 |
- <somehow create> ${ADDITIONS_DIR}/<hook>/<event>.sh |