vipsi - installation
Author: kio@little-bat.de
Keywords: vipsi shell script interpreter programming

# vipsi - shell and script language

## installation

### MacOS X

#### installing the application

to start vipsi you will need a terminal window. the terminal application can be found in Applications/Utilities and is named Terminal. (huh!)

vipsi is a script interpreter. this means that you can write script programs which shall be executed by vipsi. those script programs behave just like other shell programs: you can start them by simply typing in their name. for this to work, a script must start with the exact absolute path of it's interpreter in the first line. therefore it is often no fun to move a script interpreter to another location on the hard disk later, because you had to modify all scripts written so far or you must maintain a link at the old location. and therefore you should install vipsi into the right place just from the beginning:

    	/usr/bin

you should not have write permission to this location. so use sudo:

    	sudo cp current_location_of_vipsi /usr/bin

to insert the current_location_of_vipsi just drag vipsi's icon from a finder window into the terminal window. you will see that the complete path is pasted into the terminal window.

when you have installed vipsi properly you can start it by simply typing vipsi in a terminal window. it may be neccessary to quit and restart the Terminal application at this point.

##### how to make vipsi double-clickable

if you double click on vipsi in the finder, then the finder does not know how to start it. this is because vipsi is not an MacOS X application but rather a command line tool. if you don't like to first lauch the Terminal app and then from within the Terminal app start vipsi, just to have it handy for a quick calculation, you can make vipsi double clickable from the finder like that:

1. control-click on the vipsi icon to get the context menu
2. select "show informations" to open a file info panel
3. from the popup menu select "application to open"
4. from the popup below select "other application"
5. in the file select box uncheck "show only recommended applications"
6. select the Terminal app from the Applications folder

not that easy...

##### how to make scripts double-clickable

if you have written scripts for vipsi, there are numerous methods to execute them:

1. start vipsi and use the include instruction to include (load and execute) the script file.
2. start vipsi with a command line paramater for that file: `vipsi script_filename`.
3. start the script by simply typing it's name: `script_filename`.
   this requires that the script has been tagged 'executable' using `chmod a+x script_filename`
   and that the first line in the script is `#!/usr/bin/vipsi`.
4. start the script by double clicking on it.
   for this you must make the file executable as above
   and do the same for the script file as explained for vipsi above.

#### preparations for cgi

the cgi mechanism is not provided by your browser. it is provided by web servers like the Apapche web server preinstalled with your MacOS X. this means: cgi scripts won't work if the url in your web browser starts with `file://`. files, even those local on your own hard disk, must be accessed via http from your web server, that is, the url must start with `http://`.

first you must start your Apache web server:

- control panels > sharing > start web sharing
- test it: enter the url `http://127.0.0.1` into your web browser. this should show the standard web site of your local computer, probably the Apache documentation. enter `http://127.0.0.1/~your_unix_name` should show the file index.html in the folder Sites in your home directory.

read the Apache documentation. this should give you enough time to spend the whole summer B-]. best is, you leave the whole thing as it is for the first time.

your computer's start directory for http documents should be `/Library/WebServer/Documents`. the default directory for cgi scripts should be `/Library/WebServer/CGI-Executables`. The Apache http server is probably configured to translate `/cgi-bin/` in any url to this directory and that it only executes cgi scripts which are in this directory. in additition, this directory is not writable for you. you can either reconfigure Apache, so that it executes cgi scripts in your home directory or you can copy your scripts into `/Library/WebServer/CGI-Executables` using sudo.

after you have copied the first cgi script into `/Library/WebServer/CGI-Executables` you can test it. just enter it's url into the web browser: `http://127.0.0.1/cgi-bin/script_filename`. this should call your script which should create a page. you also may append arguments for a cgi get request in the form `...url?name=value&name=value&...` there are probably already some test cgi scripts in that directory which you can try too.

put a page which calls a cgi script in your home directory and try it.

#### notes for developers

if vipsi is frequently recompiled it may be better to put it into ~/bin/ and only put a symbolic link to that location in /usr/bin/.

#### compiling the source

get the source via cvs from the cvs repository (see links in the navigation bar). for information about cvs see the documentation on sourceforge.net, man cvs and the like B-].

cd into sub directory projects/vipsi and execute the script make. this will hopefully compile the whole thing, creating the vipsi executable right in that directory. copy it into /usr/bin or ~/bin/ as you like.

you can change some settings in options.h.

you may also create a Project Builder project where you import all the source files. there should be no real problems.

Just one note: Some files must be encoded in utf-8. You can tell Project Builder that files should be stored and reloaded later in utf-8 encoding, but you can't tell it, that they already are. please send in a bug report to Apple and work around like this: in your new Project Builder project select all those files, change file encoding for each to utf-8, and close the project. Project Builder will ask you to save the changes. Do Not Save The Changes!. reopen the project. Now no file is changed, but Project Builder knows they are all utf-8...