inter-submit.shtml

---
layout: default
title: Compiling or Testing Code with an Interactive Job
---

<p><b>To best understand the below information, users 
should already have an understanding of:</b>
</p>
<ul>
	<li>Using the command line to: navigate within directories, 
	create/copy/move/delete files and directories, and run their 
	intended programs (aka "executables").</li>
	<li><a href="{{'/helloworld' | relative_url }}">The CHTC's Intro
	to Running HTCondor Jobs</a></li>
</ul>

<h1>Overview</h1>

<p>This guide provides a generic overview of steps required to install scientific
software for use in CHTC. If you are using Python, R, or Matlab, see our specific 
installation and use guides here: <a href="{{'/howto_overview' | relative_url }}">Guides for Matlab, Python and R</a>.</p>

<!--<p>Once you've created a portable software installation, see our <a href="">Job 
Executable Creation</a> guide for more details of how to use your software in a job.</p>-->

<a name="build"></a>
<h1>1. Building a Software Installation</h1>

<p>You are going to start an interactive job that runs on the HTC build servers. 
You will then install your packages to a 
folder and zip those files to return to the submit server.</p>

<a name="version"></a>
<h2>A. Submit an Interactive Job</h2>

<p>First, download the source code for your software to the submit 
server.  Then create the following special submit file on the submit server, calling it 
something like <code>build.sub</code>. </p>

<pre class="sub">
# Software build file

universe = vanilla
log = interactive.log

# change the name of the file to be the name of your source code
transfer_input_files = <i>source_code</i>.tar.gz

+IsBuildJob = true
requirements = (OpSysMajorVer =?= 7)
request_cpus = 1
request_memory = 2GB
request_disk = 2GB

queue
</pre>

<p>The only thing you should need to change in the above file is the name of 
the source code <code>tar.gz</code> file - in the "transfer_input_files" line.</p>

<p>Once this submit file is created, you will start the interactive job by 
running the following command: </p>
<pre class="term">
[alice@submit]$ condor_submit -i <i>build.sub</i>
</pre>

<p>The interactive build job should start in about a minute. Once it has started, 
the job has a time limit of four hours - if you need more time to compile a 
particular code, talk to CHTC's Research Computing Facilitators. </p>

<h2>B. Install the Software</h2>

<p>Software installation typically goes through a set of standard steps -- configuration, 
then compilation (turning the source code into binary code that the computer can 
understand), and finally "installation", which means placing the compiled code into 
a specific location.  In most install instructions, these steps look something like:

<pre class="other">./configure
make
make install</pre>
</p>

<p>There are two changes we make to this standard process. Because you are not an 
administrator, you will want to create a folder for the installation in the build 
job's working directory and use an option in the configuration step that will install
the software to this folder. 
</p>

<p>In what follows, <b>note that anything in italics is a name that you can (and should!) 
choose to be more descriptive</b>. We use general names as an example; see the LAMMPS case 
study lower down to see what you might fill in for your own program.</p>

<ol>
<li><p>In the interactive job, create a new directory to hold your final software installation: </p>

<pre class="term">[alice@build]$ mkdir <i>program</i></pre></li>

<li><p>You'll also want to un-tar the source code that you brought along, and <code>cd</code>
into the source code folder. </p>

<pre class="term">[alice@build]$ tar -xzf <i>source_code</i>.tar.gz
[alice@build]$ cd <i>source_code/</i></pre></li>

<li><p>Our next step will be to configure the installation. This involves changing into the 
un-tarred source code directory, and running a configuration script.  It's at this 
step that we change the final installation location of the software from its default, to 
be the directory we created in the previous step. In a typical configure script, this 
option is called the "prefix" and is given by the <code>--prefix</code> flag. </p>

<pre class="term">[alice@build]$ ./configure --prefix=$_CONDOR_SCRATCH_DIR/<i>program</i></pre>

<p>Note that there are sometimes different options used.  Some program use a helper 
program called <code>cmake</code> as their configuration script. 
Often the installation instructions for a program will indicate 
what to use as a prefix option, or, you can often run the configure command with the 
<code>--help</code> flag, which will have all the options which can be added to 
the configure command.</p> </li>

<li><p>After the configuration step, you'll run the steps to compile and install your 
program. This is usually these two commands: </p>

<pre class="term">[alice@build]$ make
[alice@build]$ make install</pre></li>

<li><p>After this step, you can <code>cd</code> back up to the main working directory. </p>

<pre class="term">[alice@build]$ cd ..</pre></li>

<li><p>Right now, if we exit the interactive job, nothing will be transferred back 
because we haven't created any new <b>files</b> in the working directory, just 
the new sub-folder with our software installation. 
In order to transfer back our installation, we will 
need to compress it into a tarball file - not only will HTCondor then transfer 
back the file, it is generally easier to transfer 
a single, compressed tarball file than an uncompressed set of directories.</p>

<p>Run the following command to create your own tarball of your packages: 
<pre class="term">[alice@build]$ tar -czf <i>program</i>.tar.gz <i>program/</i></pre>
</p></li>
</ol>

<p>We now have our packages bundled and ready for CHTC!  
You can now exit the interactive job and the 
tar.gz file with your software installation will return to the submit server with you (this 
sometimes takes a few extra seconds after exiting).</p>
<pre class="term">[alice@build]$ exit </pre>

<!--<p>In order to use your new installation in a job, see our guide on <a href="">Wrapper Scripts</a>.</p>-->

<a name="case-study"></a>
<h1>2. Case Study, Installing LAMMPS</h1>

<p>First download a copy of LAMMPS and copy it 
to the submit server -- in this example, we've used the "stable" 
version under "Download a tarball": 
<a href="https://lammps.sandia.gov/download.html">LAMMPS download page</a> </p>

<p>Then, make a copy of the submit file above on the submit server, changing the 
name of the file to be transferred to <code>lammps-stable.tar.gz</code>. Submit 
the interactive job as described.</p>

<p>While waiting for the interactive build job to start, take a look at the 
installation instructions for LAMMPS: 
<ul><li><a href="https://lammps.sandia.gov/doc/Build_cmake.html">LAMMPS Install Instructions</a></li></ul></p>

<p>You'll see that the install instructions have basically the same steps as 
listed above, with two changes: 
<ol>
<li>Instead of the "configure" step, LAMMPS is using the 
"cmake" command. This means that we'll need to find the equivalent to the 
<code>--prefix</code> option for cmake. Reading further down in the documentation, 
you can see that there's this option: 
<pre class="other">-D CMAKE_INSTALL_PREFIX=path</pre>
This is exactly what we need to set the installation prefix. </li>
<li>There's extra steps before the configure step -- that's fine, we'll just 
add them to our list of commands to run. </li>
</ol>
</p>

<p>With all these pieces together, this is what the commands will look like to 
install LAMMPS in the interactive build job and then bring the installed copy 
back to the submit server. </p>

Create the folder for the installation: 
<pre class="term">[alice@build]$ mkdir lammps
</pre>

Unzip and <code>cd</code> into a build directory:
<pre class="term">
[alice@build]$ tar -xf lammps-stable.tar.gz
[alice@build]$ cd lammps-stable
[alice@build]$ mkdir build; cd build 
</pre>

Run the installation commands: 
<pre class="term">
[alice@build]$ cmake -D CMAKE_INSTALL_PREFIX=$_CONDOR_SCRATCH_DIR/lammps ../cmake </i>
[alice@build]$ make
[alice@build]$ make install </pre>

Move back into the main job directory and create a tar.gz file of the installation folder. 
<pre class="term">
[alice@build]$ cd ../..
[alice@build]$ tar -czf lammps.tar.gz lammps
[alice@build]$ exit</pre>
<br>
<blockquote>
For older version of this guide, see out <a href="{{'archived/inter-submit' | relative_url }}">archived page</a>.
</blockquote>