Language reference


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 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.

setenv (env, val), setenvTemp (env, val), envIsSet (env), envHasValue (env, value), envHasValueTemp (env, value)
These atoms let you set and test environment variables: 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.

path (val[,env])
path (value,[,env])
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 file 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.

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), choice (option, question, opt1, opt2...), fail(message)
Atoms yes, no and choice let you as 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.') }
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.

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

exists(path)
exists tests whether the argument path exists in the file system.

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. Files 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 the 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']).

alias (from,to)
Standard unix alias.

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

Packages etc.

package (PACKAGE), configure (PACKAGE)
package (PACKAGE) causes a Pacman package to be installed starting at the current working directory. The argument PACKAGE can be any Pacman package specification such as
package('BU:Python | versionGE(2.2)')
The configure atom has the same syntax and differs from package only in inducing the correct behavior when Pacman uninstalls and updates packages. The rule that you should follow is this:

The practical effect of using configure is that packages become linked together in terms of what must be uninstalled and re-installed together.

packageName (packageName)
packageName sets the name of a Pacman package to packageName. For example, if you have a package FOO.pacman with no packageName in the source code, the package name is taken to be "FOO". If, on the other hand, you have several versions of FOO in FOO-1.0.pacman, FOO-1.1.pacman, FOO-1.2.pacman, you should use packageName('FOO') in each of these files so that all three packages have the name "FOO".

description (text)
description lets you attach a description string to a package. This string is used for browsing and web displays.

url (URL), author (authorString), contact (contactString)
url, author and contact let you provide useful information about a package which is then used in browsing and web displays.

register (symbolicCacheName,cacheURL,infoString,infoURL,contactString,contactEmail)
register let's you define your own symbolic cache names. This is typically useful for large project who want to define a common set of caches with convenient names. For example,
register('BU','http://atlas.bu.edu/caches','Atlas Tier 2, Boston University','http://physics.bu.edu/~usatlas/','Saul Youssef', 'http://physics.bu.edu/~youssef/')
defines the symbolic cache name BU, so that one can refer to BU:Python, for example.

Grid related atoms

hasGlobusAccess (DN,localusername)
hasGlobusAccess tests whether distinguished name DN is mapped to local username localusername in the standard globus grid-map file.

globusAccess (DN,localusername[,position])
globusAccess is the same as hasGlobusAccess except that it adds the DN to the grid-mapfile if it's not already there. The position argument can be first or last to specify if the DN is added to the beginning or end of the grid-mapfile.

hasSshAccess (username,public_key)
hasSshAccess tests whether username has access to the installation computer using the public key public_key.

sshAccess (username,public_key)
sshAccess is the same as hasSshAccess except that if the condition is not satisfied, Pacman will add the public_key to the authorized keys file of the user username.

username (username), userExists (username[,group]), groupExists (group), userAdd (username[,group[,shell[,homedir]]]]), groupAdd (group)
username requires that the installer be a specific username. userExists requires that a user username exists on the installing system. The group can also optionally be specified. userAdd adds a user to the system if necessary with username, group, shell and home directory as indicated. For examples
username('root')                                        # requires that only root may install the package
userExists('youssef')                                   # requires that a username youssef exists
userAdd('youssef','physics','/bin/csh','/home/youssef') # creates a user youssef if necessary
If the installer doesn't have priviledge to perform these operations, Pacman will provide sensible error messages.

workspace (name,env,minmegs[,owner[,options]])
workspace sets up a working directory with at least minmegs of free space by asking the installer to choose a location. The working space is given a name name and Pacman sets an environment variable env whose value is the path of the chosen working space directory. The optional owner argument sets the ownership of the work space. The optional options argument sets properties of the work space. options is a character string which may contain any of the strings: ownerRead,ownerWrite,ownerExecute,groupRead,groupWrite,groupExecute,worldRead, worldWrite,worldExecute to indicate the file protection status of the working space. The options string may also contain temporary or permanent to indicate if the workspace is to remain after the Pacman package is uninstalled. By default, a workspace is ownerWrite and temporary. Typical examples are
workspace('Job Output','JOBOUTPUT',10000)              # makes a 100 G working space
workspace('Temporary Working Space','WORK_TMP',10000)  # makes a 10 G temporary work space
As usual, Pacman takes care of removing such workspaces and their contents unlesss you use the permanent option.


System properties

platform (plat), platformLE (plat), platformLT (plat), platformGE (plat), platformGT (plat)
platform lets you make requirements on the basic system architecture. Typical examples are
platform('linux-redhat-7.3')  # require RedHat Linux version 7.3
#
#- Require RedHat version 7.3-9 or any version of cygwin
#
{ platformGE('linux-redhat-7.3'); platformLT('linux-redhat-9') OR platformGE('cygwin') } 
You can get a list of supported platforms by doing % pacman -platforms.

tcpPorts (host,portStart,portEnd)
tcpPorts lets you require internet connectivity to host with port range as indicated. The test for connectivity is done once at installation time.

rpm (filename), rpmInstalled (filename)
rpm and rpmInstalled let you install an rpm as part of an installation procedure (rpm) or test if an rpm is already installed (rpmInstalled). As with all Pacman operations, if Pacman installs an rpm for you when a package is installed, it will also remove it when the package is uninstalled.

heapSize (bytes), stackSize (bytes), imageSize (bytes)
These atoms test the maximum memory sizes on the installing system. imageSize (bytes) guarantees that a image with size at least bytes can be run.

fileSizeSoft (bytes), fileSizeHard (bytes), fileSize (bytes)
These atoms test maximum allowed file sizes on a system. fileSize (bytes) guarantees that a file with size at least bytes can be created.

timeErrorMaximum (seconds)
timeErrorMaximum requires that the system clock on the installing system to be accurate to within seconds seconds. This is typically important for distributed computing or grid applications.

downloadTime (FILE,minimumSeconds)
downloadTime is a network performance test. It requires that the FILE (syntax is the same as in download) be downloaded to the installation site within minimumSeconds seconds.

cpuSecondsSoft (seconds), cpuSecondsHard (seconds), cpuSeconds (seconds)
Systems sometimes have built in limits on the maximum cpu time a process can used before it is automatically killed. These atoms let you require that such limits are greater than seconds seconds. cpuSeconds requires that the minimum of the soft and hard limits be greater than the seconds argument.

openFileDescriptorsSoft (ndesc), openFileDescriptorsHard (ndesc), openFileDescriptors (ndesc)
These atoms test the maximum allowed number of open file descriptors on a system. openFileDescriptors (ndesc) guarantees that at least ndesc file descriptors can be open at once.

runningProcess (processName)
runningProcess requires that processName be a currently running process at the time of installation.

fileCopyMinimumMegsPerSecond (path,minimumMegsPerSecond)
fileCopyMinimumMegsPerSecond lets you test disk writing speed at the installation machine. This requires that at least minimumMegsPerSecon can be copied from one file to another at location path.


Versions, releases tags, natively installed software

version (text), versionLE (text), versionLT (text), versionGE (text), versionGT (text)
Version lets you assign a version string to a package. Versions, releases and tags have no intrinsic meaning within Pacman; they are just strings with standard lexical ordering. Typically, one does something like
version('1.1')  # this package is version 1.1
in package Foo. Then, in another package, you can do
package("Foo | { versionGE('1.0'); versionLT('2.0') OR version('3.0-beta') }")
to select particular versions, or, similarly, on the command line
% pacman -get "Foo | { versionGE('1.0'); versionLT('2.0') OR version('3.0-beta') }"
In the Pacman browsing functions, if you do -l -d versions or -lc -d version the versions of packages will be displayed.

release (text), releaseLE (text), releaseLT (text), releaseGE (text), releaseGT (text)
Similar to version above.

tag (text), tagLE (text), tagLT (text), tagGE (text), tagGT (text)
Similar to version and release above.

linuxKernel (text), linuxKernelLE (text), linuxKernelLT (text), linuxKernelGE (text), linuxKernelGT (text)
These atoms let you require versions or version ranges of the standard linux kernel.

gccVersion (text), gccVersionLE (text), gccVersionLT (text), gccVersionGE (text), gccVersionGT (text)
These atoms let you require versions or version ranges of the standard linux kernel.

pythonVersion (text), pythonVersionLE (text), pythonVersionLT (text), pythonVersionGE (text), pythonVersionGT (text)
These atoms let you require versions or version ranges of the standard linux kernel.

pythonVersion (text), pythonVersionLE (text), pythonVersionLT (text), pythonVersionGE (text), pythonVersionGT (text)
These atoms let you require versions or version ranges of the standard linux kernel.

sshVersion (text), sshVersionLE (text), sshVersionLT (text), sshVersionGE (text), sshVersionGT (text)
These atoms let you require versions or version ranges of the standard linux kernel.

perlVersion (text), perlVersionLE (text), perlVersionLT (text), perlVersionGE (text), perlVersionGT (text)
These atoms let you require versions or version ranges of the standard linux kernel.

perlVersion (text), perlVersionLE (text), perlVersionLT (text), perlVersionGE (text), perlVersionGT (text)
These atoms let you require versions or version ranges of the standard linux kernel.

pacmanVersion (text), pacmanVersionLE (text), pacmanVersionLT (text), pacmanVersionGE (text), pacmanVersionGT (text)
These atoms let you require versions or version ranges of the standard linux kernel.

If you want to test versions of software not in this list, a good option is to use shellOutput, shellOutputLE, etc.


Executing shell commands

shell (command), shellDialogue (command)
shell and shellDialogue let you execute standard shell commands as part of a Pacman installation. In general, you should use Pacman syntax instead of shell commands whenever possible for several reasons: Several command line switches in -v help and -ask help relate to shell commands. An installer can, for instance, use -ask shell and Pacman will stop and ask permission before executing any of these shell commands. From the Pacman perspective, if a shell command returns no exit code, it is considered to have successfully executed. The shell atom sends sysout to a log file, so if you are executing a script that interacts with the installer, you should use shellDialogue.

shellOutputContains (command,text)
shellOutputContains executes the shell command command and requires that the output contains text.

shellOutputEQ (command,text), shellOutputLE (command,text), shellOutputGE (command,text)
shellOutputEQ,LE,GE let's you compare the output of a shell command to a provided string. This is convenient for requiring versions of natively installed software. For example, if you want to require GNU Wget at least version 1.9, you can do
shellOutputGE('wget -v','GNU Wget 1.9')
this requires both that wget is available and that the start of the resulting output matches or exceeds the provided string.

uninstallShell (command)
uninstallShell let's you specify shell commands which are only executed when a package is uninstalled. This is typically useful for cleaning up the result of other shell commands.


File manipulation

isWorldRead (path), isWorldWrite (path), isWorldExecute (path), isGroupRead (path), isGroupWrite, isGroupExecute, isOwnerRead (path), isOwnerWrite (path), isOwnerExecute (path)
These atoms test whether files or directories are world/group/owner read/writable.

setWorldReadable (path), setWorldWriteable (path), setWorldExecutable (path), setGroupWriteable (path), setGroupExecutable (path), setOwnerReadable (path), setOwnerWriteable (path), setOwnerExecutable (path)
These are the same as the previous atoms except that they will set the indicated file access if it has not been done alreay. As with all Pacman operations, the change in file access will be undone when the Pacman package is uninstalled.

ownedBy (path[,username])
ownedBy tests that the file specified by path is owned by username. The default for username is the username of the installer.

chown (path[,username]), chownR (path[,username])
chown changes the ownership of a file to username. username defaults to the username of the installer. chownR recursively changes the ownership of a directory tree.


Pacman Headquarters