Basics

download (FILE), downloadUntar (FILE [, env]), downloadUntarzip (FILE [, env]), untarzip (FILE [, env])

These atoms are used to download files to the current working directory. The FILE argument may be a full URL or a file specified with SSH syntax or a file specified relative to a symbolic cache name or a local file. Here are examples all downloading the same file

• download ('http://atlas.bu.edu/caches/tarballs/foo.tar.gz')
• download ('youssef@atlas.bu.edu:/caches/tarballs/foo.tar.gz')
• download ('BU/tarballs/foo.tar.gz')
• download ('/atlasgrid/caches/tarballs/foo.tar.gz')

The optional env argument causes Pacman to set an environment variable to the full path of the top level untarred directory. The download atom simply downloads; downloadUntar and downloadUntarZip are identical and both automatically untar and unzip as necessary. Pacman guarantees that untarring does not overwrite existing files unless you override this feature with -allow tar-overwrite. Note that for untarzip(FILE), FILE must be in the current working directory (use cd otherwise to cd to the right location).

md5check (path, md5string)

md5check (path, md5string) checks if the file at path has md5 checksum-hexstring md5string.

setenv (env, val), setenvTemp (env, val), envIsSet (env), envHasValue (env, value), envHasValueTemp (env, value)

These atoms let you set and test environment variables:

• setenv (env, val) assigns environment variable env the value val. Pacman both guarantees that the environment variable that you set maintains it's value independent of any other packages and it also guarantees this value in setup scripts that Pacman generates.
• envIsSet (env) requires that the environment variable has been set.
• envHasValue (env, value) requires that the environment variable has been set to the value value and guarantees that this is true

setenvTemp and envHasValueTemp differ from their non-temp versions in that they do not guarantee a permanent condition and do not get put setup scripts.

setenvShell (env, command)

setenvShell (env,command) executes the shell command command and, if the command returns without an error code, sets environment variable env to the first non-blank line of the shell command output.

setenvShellTemp (env, command)

Same as setenvShell except that the set environment variable is temporary in the same sense as setenvTemp above.

path (val [, env [, options]])

path (value,[,[env,options]]) let's you add directories to standard unix path searching variables like the standard PATH and LD_LIBRARY_PATH. env defaults to PATH. Pacman checks that the directories specified exists and guarantees that executable files in directories added this way are consistent. If, for example, you do path('/usr/bin/') and path('/usr/local/bin') and both contain the file python, Pacman will report an error. This guarantees that as an author of a Pacman package files that you add to paths are maintained independent of other packages. Sometimes it is useful to suppress this checking, in which case you should put the word "no-check" in the optional options argument. If "back" appears in the options string, Pacman adds the path to the end of the path variable list rather than the (default) front.

mkdir (path), mkdirPersistent (path)

mkdir (path) makes a new directory and checks it's existence over time. When a package containing mkdir is uninstalled, the directory and it's contents are removed by Pacman. mkdirPersistent remains after a package is uninstalled.

message (text), echo (text)

Either of these prints a message.

cd (path), cu (username)

cd (path) has the same effect as % cd path as a unix shell command. cd () undoes the previous cd command. Similarly, cu (username) changes the username of the installing process and cu () undoes the previous username change. cu only works if the installer is the superuser.

yes (question), no (question), setenv (env), choice (option, question, opt1, opt2...), fail (message)

Atoms yes, no, setenv with one argument and choice let you ask questions at installation time and remember the answers for future installations. This is typically used with OR branching to have a package. For example,

 { yes('Do you want to print "FOO"?'); message('FOO') OR message('not printing FOO') }

shows how to use yes to ask a question and follow the first branch if the answer is 'yes'. Similarly, no is satisfied as a logical condition if the answer to the question is 'no'. You can use choice when there are multiple possibilities as in

 { choice(  'Red','Choose a color','Red','Green','Blue'); message('Red chosen'  ) OR
   choice('Green','Choose a color','Red','Green','Blue'); message('Green chosen') OR 
   choice( 'Blue','Choose a color','Red','Green','Blue'); message('Blue chosen' ) }

Use fail(message) to cause an installation to fail with an error message as in

 { yes('OK to make a new directory?'); mkdir('foo') OR fail('No permission to make foo.') }

If you want to set an environment variable FOO to a value chosen by the installer, simply do

 setenv('FOO')

and Pacman will ask a question and set FOO appropriately. All of these atoms save and remember the answers provided, so that the answers don't have to be repeated when the software is updated or removed and re-installed. The installer can always choose to ignore this saved information by using -ignore-cookies.

exists (path)

This tests that the file path exists at installation time.

askUntilFileExists (path)

This tests that the file path exists at installation time. If it does not exist, the installer is asked to put the file in place and continue.

watch (path)

Tests for the existence of a file or directory tree. Pacman will record the last modified time of the file or director tree contents. If an installer then does

% pacman -verify

Pacman will report an error if any of the files have been modified.

which (filename)

which tests that filename is in the user's standard PATH as in the familiar unix command.

copy (fromPath, toPath), cp (fromPath, toPath)

Copies files or directory trees.

copyReplace (fromFile, toFile, matchString, replaceString)

Copys a text file with string replacement.

grep (text, path [, comment])

Tests if the file path contains the text text. Lines beginning with the optional comment (default "#") character are ignored for the purpose of testing the condition.

freeDisk (freemegs [, path])

Test whether the current working directory is in a file system with at least freemegs megabyte of free space. This is only tested once at installation time. The optional path variable let's you test the free space in other parts of the installer's file system.

cat (path)

Prints a file during installation as with the familiar unix command.

ls (path)

Prints the contents of a directory as with the familiar unix commmand.

softLink (linkFrom, linkTo)

Create a soft link.

insertLine (text, path [, justAfterLineContaining])

Reversibly insert a line of text text into a text file at path. The optional third argument lets you insert a text line just after a line containing the specified text justAfterLineContaining.

textFile (path, lines)

textFile creates a text file containing lines. The lines argument must be a list of text strings in brackets as in textFile ('foo.csh',['#','# - comment','#'])

mail (userEmail [, subject [, body]])

Mail sends an email message to userEmail with optional subject subject and optional text body body. If the body argument is used, it must be a list of text strings in brackets as in mail ('youssef@bu.edu','hello',['hi','there']).

true (), false ()

true() is a condition which is guaranteed to always be satisfied and false() is guaranteed never to be satisfied.

launchWebBrowser (url)

Launches a web browser to the indicated page.

Pacman Headquarters