View source for Install 3rd-party programs or libraries

A lot of great software has been written by people not in our group, and it's to our advantage to be able to make use of it.  This HOWTO explains how to install a 3rd-party project (that is, a program or library) into [[$G]] so that everyone in the group can use it.  This is easiest if you can get a simple source tree for the project, but we can even deal with complicated source trees and binary-only projects.

'''Remember to never copy files directly into <code>$G</code>!'''  Everything in <code>$G</code> should get there by being checked into CVS.

==Install a simple source tree==
In this case, installing a 3rd-party project is identical to checking in and installing one you wrote yourself.
# Create a new directory for the project (''not'' in <code>$G</code> but somewhere in your homedir) and copy the source tree into a subdirectory of this, say <code>src</code>.  Remember to make sure the tree is clean; no object files or other binaries.
# Create a Makefile in ''your'' directory (not the <code>src</code> directory that contains the project's source tree) and give it some rules:
#* The <code>all</code> target should simply call the source's own Makefile.
#* The <code>install</code> target should copy the resulting executables, headers, libraries, and documentation into <code>$G/bin</code>, <code>$G/include</code>, <code>$G/lib</code>, and <code>$G/man</code> respectively.
# [[Put your code into CVS in $G|Import the project into CVS as normal]].

Here's an example Makefile for the NIFTI medical image format library:
<pre>
all:
	# NIFTI lib source code is one directory down
	# to preserve the Makefile that comes with it
	cd src; make all

install:
	cd src; make doc
	# we have to do some gymnastics to avoid copying the CVS directory
	find src/bin -maxdepth 1 -type f -print0 | xargs -0 -I '{}' cp '{}' $(G)/bin
	mkdir -p $(G)/lib/nifti
	cp -f src/lib/*.a $(G)/lib/nifti
	mkdir -p $(G)/include/nifti
	cp -f src/include/*.h $(G)/include/nifti
	mkdir -p $(G)/shared/man/nifti
	cd src/docs/html; cp -f *.html *.png *.css *.gif $G/shared/man/nifti
</pre>

==Install a complicated source tree==
In some rare situations, you can't put all the project's source into our CVS tree.  In this case, the goal is to package everything you've got up into a <code>.zip</code> file and make the build and install scripts temporarily unpack the source tree.
# If you already have a <code>.zip</code> file for the source tree, continue on.  If not, use the <code>zip</code> command to create an archive.
# Move the <code>.zip</code> file into its own directory and create a Makefile there.
#* The <code>all</code> target should unzip the archive and build it.
#* The <code>install</code> target should copy the resulting executables, headers, libraries, and documentation into <code>$G/bin</code>, <code>$G/include</code>, <code>$G/lib</code>, and <code>$G/man</code> respectively.
# Move the <code>.zip</code> file somewhere else temporarily and [[Put your code into CVS in $G|import the project into CVS as normal]] with just the Makefile in the directory.
# Move the <code>.zip</code> file into the appropriate <code>$G/src/&lt;projname&gt;</code> directory, check it in with <code>cvs add -kb &lt;archivename&gt;</code>, and then commit.

Here's another Makefile for the NIFTI library, but this time extracting the source code on the fly:
<pre>
all:
	unzip -ou nifti.zip
	# nifti.zip has a root directory called "src"
	cd src; make all

install:
	cd src; make doc
	# we have to do some gymnastics to avoid copying the CVS directory
	find src/bin -maxdepth 1 -type f -print0 | xargs -0 -I '{}' cp '{}' $(G)/bin
	mkdir -p $(G)/lib/nifti
	cp -f src/lib/*.a $(G)/lib/nifti
	mkdir -p $(G)/include/nifti
	cp -f src/include/*.h $(G)/include/nifti
	mkdir -p $(G)/shared/man/nifti
	cd src/docs/html; cp -f *.html *.png *.css *.gif $G/shared/man/nifti

===Advanced: use <code>wget</code>===
Sometimes it makes sense to have the build and install scripts just download the project directly, rather than checking an archive into our CVS.  Be careful about doing this, as versions and URLs change over time.

Rather than download the project's <code>.zip</code> file yourself and then check that in, you can add a <code>wget</code> command to the Makefile to download it, and then unzip, build, and install it as above.

Here's an optional <code>download</code> target that could be appended to the Makefile above and added to the <code>all</code> step:
 download:
 	rm -rf src nifti.zip
 	wget -rq --reject "*.html*" --nH --cut-dirs=2 <nowiki>http://nifti.nimh.nih.gov/pub/dist/src/</nowiki>
 	zip -r nifti.zip src
 	rm -rf src

==Install binary files directly==
If you don't even have a <code>.zip</code> file of the source tree for a project, then you have no other choice but to put the actual binary library file into CVS.
# Put all the binaries you want to install into their own directory.
# Create a Makefile in that directory that will respond to <code>make all</code> and <code>make install</code>.
#* For <code>make all</code> you can just print out "Nothing to do for this project."
#* For <code>make install</code>, use <code>gfxinstall3</code> to install the files in the proper places in <code>$G</code>.
# Now move the binaries out of the directory and import the directory into CVS.
# Copy the binaries into the new <code>$G/src/&lt;projectname&gt;</code> directory, add each one with <code>cvs add -kb &lt;filename&gt;</code>, and then commit.

[[Category:HOWTO]]