gnostic ======= gnostic: adjective 1 of knowledge. 2 having special mystic knowledge. noun (Gnostic) early Christian heretic claiming mystical knowledge. -- Merriam-Webster on-line dictionary. Overview -------- gnostic is a program which executes shell scripts according to certain criteria. It is aimed at applications where there is a need to codify some types of "recipes" for doing things. Installation ------------ Read the INSTALL file for detailed instructions. The most straight-forward way to install gnostic is by executing:: ./configure make make install gnostic doesn't depend on any third-party libraries and it's supposed to compile and run cleanly on any UNIX-like operating system. Documentation ------------- Full API documentation can be generated with doxygen. There's a doxy.cfg file with some defaults that the users/developers can change to suit their needs. An user's guide is present (currently as a work-in-progress) in the doc/ subdirectory. There are also two manual pages which are installed by default. To generate all the documentation type:: make doc apidoc Getting started --------------- The best way to get a feeling of how gnostic works is to try some of the sample taskfiles present in the examples/ subdirectory. It is very easy to start writing your own taskfiles specially if you're already familiar with make(1). One could start trying with:: $ gnostic examples/environ.gns environ When gnostic is invoked this way it lists all the tasks present in the given task file. By convention, the main one will appear at the beginning. In this example we have only one task: environ. Let's ask gnostic to execute it:: $ gnostic examples/environ.gns environ gnostic: Executing `environ'. BASH=/bin/sh BASH_VERSINFO=(="2" ="05b" ="0" ="1" ="release" ="i586-mandrake-linux-gnu") BASH_VERSION='2.05b.0(1)-release' BROWSER=/usr/bin/mozilla . . . USER=rwx WINDOW=1 WINDOWID=12582914 XAUTHORITY=/home/rwx/.Xauthority XMODIFIERS=@im=none _=/bin/sh gnostic: Task `environ' exited with status 0. $ As you can see this is a fairly trivial task. It invokes BASH's builtin command set(1) to print out the task's environment. But we can use it demonstrate at least one feature of gnostic: passing parameters:: $ gnostic examples/environ.gns environ fnord=23 foo=bar gnostic: Executing `environ'. . . . _=/bin/sh fnord=23 foo=bar gnostic: Task `environ' exited with status 0. $ The parameters passed become part the environment of the executed task. The following is a more useful example of tasks and parameters at work:: $ gnostic examples/netmap.gns ping addr=127.0.0.1 scriptdir=examples gnostic: Executing `ping'. gnostic: Executing `ping-requisites'. gnostic: Task `ping-requisites' exited with status 0. PING 127.0.0.1 (127.0.0.1) 56(84) bytes of data. 64 bytes from 127.0.0.1: icmp_seq=1 ttl=64 time=0.295 ms 64 bytes from 127.0.0.1: icmp_seq=2 ttl=64 time=0.060 ms 64 bytes from 127.0.0.1: icmp_seq=3 ttl=64 time=0.057 ms 64 bytes from 127.0.0.1: icmp_seq=4 ttl=64 time=0.056 ms 64 bytes from 127.0.0.1: icmp_seq=5 ttl=64 time=0.057 ms --- 127.0.0.1 ping statistics --- 5 packets transmitted, 5 received, 0% packet loss, time 4000ms rtt min/avg/max/mdev = 0.056/0.105/0.295/0.095 ms gnostic: Task `ping' exited with status 0. $ After this step it is advisable to delete the left-over data (perhaps after taking a look at it) located in /tmp/gnostic and start reading the appropriate man pages and the rest of the examples.