Note: This web site is only kept up to date for OSG Software 1.2 (VDT 2.0.0). If you are looking for information for the most recent release, the RPM-based OSG Software 3.0, please see the OSG documentation web site

Symlinker script

The script currently lives in SVN in vdt/branches/vdt-2.0.0-native/build-scripts/native-symlinker If you make modifications, there is a test suite in build-scripts/test-native-symlinker.t that you should run afterwards.

Invoking the script manually

If you want to run the symlinker manually as part of an RPM or Debian build process, this is the usage:

native-symlinker.pl [options] PACKAGE_NAME INSTALL_ROOT

Options are:
    --cleanup CLEANUP_FILE  Override path of cleanup filelist.
                            Files in the cleanup filelist will be removed
                            on uninstall (Debian only).
                            Default value is ./debian/extra-cleanup-files.txt

    --filelist FILELIST     Override name of filelist.
                            The names of the symlinks that were created will
                            be appended to this.  Default values are:
                            ./PACKAGE_NAME.rpmfilelist      for RPMs and
                            ./debian/PACKAGE_NAME.install   for Debian.

    --links LINKS_FILE      Override the name of the links file which will be
                            used to determine what symlinks to create.
                            Default values are:
                            ./vdtrpmtool/PACKAGE_NAME.links for RPMs and
                            ./debian/PACKAGE_NAME.links     for Debian.

    --no-cleanup            Do not append symlinks to the cleanup file.
    --no-filelist           Do not append symlinks to the filelist.
    --deb
    --debian                Force Debian package format.
    --rpm
    --redhat                Force RPM package format.
(INSTALL_ROOT is also known as BUILDROOT on RPMs)

Symlinking as part of an NMIRPM build

This involves adding a links section to the native.conf. The NMIRPM module will take care of running the script at the appropriate time, so you don't have to worry about arguments. It uses the contents of the links section as the links file.

Optionally, you may add a links_pre section that can be used to set environmental variables that can be used in the links section. The format of this is just BASH. Don't forget to export any variables you make.

Links file format

Basic

The majority of the links file will be a set of 'location', 'target' pairs separated by an arrow (->). The location is the directory where the symlink(s) will be created; the 'target' is where the symlink(s) will point to.

Example:

/usr/bin -> /opt/vdt/bin/*
/etc -> /opt/vdt/etc/*.conf
    

The first line says 'create symlinks in /usr/bin for each entry in /opt/vdt/bin'. The second line says 'create symlinks in /etc for each .conf file in /opt/vdt/etc'.

You may use environment variables in your links files:

/usr/bin -> $VDT_LOCATION/bin/*
    

Note that a symlink for each directory entry matching the glob will be created, i.e. not just each file. So if there's a directory $VDT_LOCATION/bin/utils, then the line in the example above will create a symlink /usr/bin/utils -> $VDT_LOCATION/bin/utils. To avoid things like that we have the skip section.

Skip section

The skip section determines what targets should not be symlinked, even if they match a glob or a line somewhere in the file.

Example:

<skip>
    /opt/vdt/bin/utils
</skip>
/usr/bin -> /opt/vdt/bin/*
    

This example creates symlinks for everything in /opt/vdt/bin, except for /opt/vdt/bin/utils. Each line under skip is a single target or a glob of targets. Symlinks for these targets will not be created. You may have multiple skip sections in the file, but their order does not matter.

Rename entries

The 'location' part of each symlink line is assumed to be a directory; this directory is created if it does not exist, and the basename of the symlink is the same as the basename of the target. What this means is that if you write /usr/bin/gsissh -> /opt/vdt/bin/ssh, the symlink that is created will be /usr/bin/gsissh/ssh pointing to /opt/vdt/bin/ssh, which is not what you want.

In order to get around this, prefix the line with rename. Example:

rename /usr/bin/gsissh -> /opt/vdt/bin/ssh
    
Then, the symlink will be named /usr/bin/gsissh and it will point to /opt/vdt/bin/ssh. Globs cannot be used with this.

Wrapper section

Sometimes an executable requires environmental variables to set or setup/cleanup steps to be run that should be transparent to the user. In this case you might want to have the user-visible symlink point to a wrapper script. Often you may want to have several executables using the same wrapper script, which will use the name that it was called as to determine which actual binary to run. You use a wrapper section to specify this. Example:

<wrapper path="/opt/vdt/bin/_globus_wrapper">
    /usr/bin -> /opt/vdt/bin/globus*
</wrapper>
    
This means 'make a symlink in /usr/bin for everything in /opt/vdt/bin that starts with globus, and have that symlink point to /opt/vdt/bin/_globus_wrapper'. You would then structure '_globus_wrapper' to check $0 to find out what it was called as, then run the appropriate binary.

Note that the symlinker does not create the wrapper script, nor does it check to see if it exists.

Examples

This is a complete native.conf file for xrootd-libs. Note the links_pre and links parts: Running eval `perl -V:installvendorlib` puts the location of the vendor_perl subdirectory into the $installvendorlib variable. Then we need to export it.

name            xrootd-libs
summary         Xrootd shared libraries
version         !!XROOTD_RPM_VERSION!!
release         !!XROOTD_RPM_RELEASE!!

description     <<END
Xrootd is a high-performance network file system designed for large data
files in the grid world.

This package contains the Xrootd shared libraries.
END

flags           make_debuginfo_packages

url             !!XROOTD_URL!!

build           <<END
# Remove components that end up in the other xrootd-essentials RPMs
# (i.e. xrootd-static and xrootd-devel)
rm -rf $BUILD_ROOT_VDT/xrootd/include
rm -f $BUILD_ROOT_VDT/xrootd/lib/*.a
END

links_pre       <<END
eval `perl -V:installvendorlib`
export installvendorlib
END

links           <<END
/usr/lib -> $VDT_LOCATION/xrootd/lib/*.so
$installvendorlib -> $VDT_LOCATION/xrootd/lib/*.pm
END

include         xrootd-changelog.conf
include         xrootd-license.conf

obsoletes       xrootd-essentials <= 20100315.1007-1.vdt2

This is what the vdt-gsi-openssh-server.links file for the LIGO GSISSH package would look like with the new format:

# symlink to same name
usr/sbin/            ->  opt/vdt/globus/sbin/gsi*
usr/share/man/man8/  ->  opt/vdt/globus/share/man/man8/gsi*

# symlink to new name
rename etc/gsisshd_config                   ->  opt/vdt/globus/etc/sshd_config
rename usr/share/man/man5/gsisshd_config.5  ->  opt/vdt/globus/share/man/man5/sshd_config.5
Note that neither leading nor trailing slashes make any difference; paths are assumed to be absolute.