How to build and install an app
The basic workflow to build an app using fasrcsw is:
- get the source
- create and partially complete a spec file, using the template as a starting point
- do a preliminary build of the software to see what it creates, in order to know what to put in the module file
- complete the spec file and build the final rpm(s)
- install the rpm(s)
- commit changes and move the build outputs to production repos and archives
Once you're comfortable with the workflow, you can probably just use HOWTO-short instead of this doc.
The default behavior and templates are designed to work with GNU-toolchain-style software packages, i.e. things that use
make install with standard options, with as little modification as possible.
As an example, this document uses the automake hello-world example,
amhello-1.0.tar.gz, distributed with automake.
If you're new to fasrcsw, try building and installing amhello first, to get the hang of things.
Get ready to build software:
- make sure you've cloned and configured fasrcsw according to this
- make sure you're logged into the build host
- make sure you're logged into your normal user account (with sudo privilege), not root
cd to your personal fasrcsw clone.
Make sure your clone is up-to-date and your environment is pristine, and setup the environment:
There will now be two environment variables defined that are used in the instructions below --
$FASRCSW_DEV is the location of your personal clone, and
$FASRCSW_PROD is the production one, the central location for your organization's software.
Set these variables particular to the app you're installing:
VERSION are whatever the app claims, though some adjustments may be required -- see this FAQ item.
RELEASE is used to track the build under the fasrcsw system and should be of the form
## is a two-digit number.
If this is the first fasrcsw-style build, use
fasrc01; otherwise increment the fasrc number used in the previous spec file for the app.
TYPE, a major purpose of fasrcsw is to manage entire software environments for multiple compiler and MPI implementations.
Apps are therefore categorized by their dependencies (see this FAQ item more about this initially non-intuitive convention, adopted from TACC):
- A Core app is one that does not depend on a compiler or MPI implementation.
- A Comp app is one that depends upon compiler but not MPI implementation. It's conventional to build MPI implementation apps against multiple compilers, so The MPI apps themselves are Comp apps.
- A MPI app is one that depends upon MPI implementation, and therefore upon compiler, too.
TYPE to the string
Unless you have a reason to build with the newer compilers or you need to build against MPI, just set
TYPE=Core (see this FAQ item for more info).
For example, to test the simple Core case with
export NAME=amhello ; export VERSION=1.0 ; export RELEASE=$USER ; export TYPE=Core.
Note that this breaks convention and uses
$USER for the
RELEASE instead of
fasrc01 -- this is to avoid people clobbering each other during a demo.
amhello example can be used to test all app types, even though the dependencies are not real.
Get the source code
Put a copy of the app source archive in the location for the sources.
wget --no-clobber http://...
amhello, which is a bit complicated because it's a tarball within another tarball, see this FAQ item.
Create a preliminary spec file
Change to the directory of spec files:
Create a spec file for the app based upon the template:
cp -ai template.spec "$NAME-$VERSION-$RELEASE".spec
Now edit the spec file:
and find and address all the appearances of
For example, there are sections where
make install called; adjust them if necessary.
For GNU-toolchain-style software, including amhello, the template code works as-is.
Just complete everything up to where
modulefile.lua is created (the part where you need to know what environment variables to change).
The next step will provide the necessary guidance on what to put in the module file.
If the app you're building requires other apps, follow the templates for loading the appropriate modules during the
%build step and having the module file require them, too.
See this FAQ item for more details.
If the build process is different for different compilers and/or MPI implementations, see this FAQ item.
Do a trial build and inspect its output
The result of the above will be enough of a spec file to basically build the software.
However, you have to build it and examine its output in order to know what to put in the module file that the rpm is also responsible for constructing.
Run the following to do a partial build, up to where that module file is built.
This will print suggestions for what to put there:
Eventually, after a few iterations of running the above and tweaking the spec file in order to get the software to build properly and even get to the trial step, the output will show something like this near the end:
*************** fasrcsw -- STOPPING due to %define trial yes ******************
Look at the tree output below to decide how to finish off the spec file. (`Bad
exit status' is expected in this case, it's just a way to stop NOW.)
| `-- hello
4 directories, 3 files
Some suggestions of what to use in the modulefile:
error: Bad exit status from /var/tmp/rpm-tmp.B5l2ZA (%install)
Bad exit status is expected in this case.
README and other docs in the root of the installation is something manually done by fasrcsw just out of personal preference.
Finish the spec file
Based upon the output in the previous step, finish the spec file by writing what goes in
Usually this is as simple as copy-n-pasting the suggested block of text at the end of the
make trial output.
Build the rpm(s)
Now the rpm (or set of rpms) can be fully built:
For a Core app, only one rpm is built, but for Comp and MPI apps, multiple rpms are built.
In the latter case, possibly only one combination is failing to build; see this FAQ item to debug just that without rebuilding the working ones each time.
Once that runs successfully, double check that all worked as expected.
You can list and inspect the rpms that were built with the following:
make filequery | less
--scripts to the latter to see how the module file symlink is created in the
For each package you should see that:
- all the metadata looks good
Relocationsand all files are under an app-specific prefix under
Test if the rpm(s) will install okay:
This currently only tests that the rpm is installable, and that almost never fails.
Note that it does not test if the loading the module or running the software actually works.
Install the rpm(s)
Finally, install the rpm(s):
Check that the rpm(s) installed:
and the module(s) is/are there.
For a Core app:
module load $NAME/$VERSION-$RELEASE
#...test the app itself (for amhello, run `hello')...
module unload $NAME/$VERSION-$RELEASE
If you want to erase and retry the process,
Save your work
If you're just trying things out with
make uninstall and remove your spec file (
Otherwise, for production apps, copy the rpms to the production location and commit/push all your modifications to the fasrcsw git remote.
The following will do all of this:
For completeness, as root, pull them to the production clone:
sudo git pull
This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License. Permissions beyond the scope of this license may be available at Attribution.