Installing Classes and Packages
The mathematics department's computers have the
hmcthesis, and other locally
created classes and support files installed so that they work
without your having to do anything special. You can copy the
template file to a new directory and start working immediately—the college's logo (and seal, where appropriate), the bibliography
style, and some of the configuration options “just work”.
But if you want to work on your own machine, you'll need to have local copies of several different files available for use by your machine's TeX system.
Although it's possible to use LaTeX packages or classes without
installing them (by placing them in your working directory), we
encourage you to install the files into a “
tree” so that they will be usable by any document you create on
your system. Installing support files also allows you to update
them in one place, which means it's easy to bring all your
documents using a particular class or package up to date, and to
be sure that each document is using the latest version of files
that you have installed.
Another advantage of installing the classes and supporting
files in a
TEXMF tree is that it allows you to avoid
cluttering up your document directories—we actually require
submitted code for Clinic reports and theses to not have our class
and support files mixed in with the files you've created.
Modern TeX systems contain thousands of files, including classes and packages, but also several different kinds of font and font-related files; support and format files for bibliographies, indexes, and other document elements; and support for different macro systems built on TeX, including Plain TeX, LaTeX, ConTeXt, and others—there are roughly 66,000 files in a typical TeX Live installation.
Each program in a TeX system uses a different combination of these files, and if each program had to search through all the files to find the files it needed, the system would be quite slow. To make the task easier, TeX-system developers created the TeX Directory Structure, or TDS, which defines a standard hierarchical file system to be used to sort components into standard locations.
Furthermore, most TeX systems support multiple TDS-compliant trees that are searched in a particular order, which means that the TeX system can have its own set of files that can be managed separately from those installed by a system administrator or by individuals.
The TeX Directory System is defined and described in a document maintained by the TUG Working Group on a TeX Directory Structure. The whole tree is fairly complex, but most people only need to worry about implementing a small subset of the whole tree.
TEXMF trees are usually shared by all
users of a computer. Their exact location depends on the TeX
system in use, but some common locations are shown in the
|TeX Live (Linux/Unix)||
|MacTeX (Mac OS X)||
|TeX Live (Windows)||
TEXMF trees are supported on some systems by default, and
on others with special configurations. They're most useful when
working on a system shared by other users (such as the math
workstations), especially when end users don't have access to
system directories, or might want to override the choices made by
For Unix-like systems such as Linux and Mac OS X, personal
trees can be set up in the user's home directory and are
automatically searched. The locations of these trees are shown in
the following table:
|TeX Live (Linux/Unix)||
|MacTeX (Mac OS X)||
|TeX Live (Windows)||
MikTeX Root Directories
The MikTeX system for Windows doesn't support local or personal
TEXMF trees by default, although you can set up such
directories by using its configuration tools. The Settings tool
(in the MikTeX program group) includes a “Roots” tab. You can
create a directory (such as
C:\LOCALTEXMF) and then
use the Roots tab to add that directory. The directory you create
will need to have subdirectories conforming to the TeX Directory
Once you've added your new root, you should use the Up and Down buttons to ensure that your root is searched before the other roots. (Alternatively, you can put your root last, and you will always get the version of packages that come with or were installed by MikTeX, but packages you've installed that aren't included in MikTeX's system will be used instead of those that you've installed.
If you add files to your local root after you've added the root
to MikTeX's list of root directories, you will need to refresh the
filename database by hand so that MikTeX's component applications
can find the new files. [MikTeX's filename database is equivalent
ls-R files that Unix TeX systems use; on Unix
systems, local and personal
TEXMF trees are searched
directly, so you don't need to index them.]
To update the database, start the MikTeX Settings application and select the General tab. You should see a pane labeled Maintenance, and inside that pane a button labeled Refresh FNDB. Click the button, and wait while MikTeX rescans its file roots. Once it's done, you should be able to use your new files.
Note that you shouldn't need to refresh the database by hand after installing LaTeX packages with the MikTeX package manager; the database should be rebuilt as part of the installation process.
Obtaining the Class and Support Files
There are two basic elements that you will need to produce your final Clinic report or thesis:
- The class and its support files, which include the HMC logo (and seal, for some classes) and some configuration files; and,
hmcmath.bstbibliography style file. [There is also a
hmcmathannote.bstfile that provides an annotated version of the
hmcmathbibliography style, which might be useful if your advisor wants an annotated bibliography; see the discussion of local BibTeX bibliography styles for details.]
You can either download a
tar file or ZIP archive
containing the necessary files or copy them from a mathematics
Downloading the Class and Support Files
The bibliography style files can be downloaded from our bibliography style page.
Copying the Class and Support Files
The class, bibliography-style, and support files can also be
copied from any departmental Linux system. The latest version of
the class files and support files can always be found in
the files from the directories without version numbers to
get the latest version (e.g.,
hmcclinic rather than
hmcmath bibliography-style files can be
Installing the Class and Support Files
As noted, there are many possible subdirectories for local and
TEXMF trees. For installing the basic
support files for use with our classes you only need a small
number of these subdirectories, as shown in the following figure:
texmf/ bibtex/ bst/ hmcmath/ ... tex/ latex/ hmcclinic/ ... hmcthesis/ ...
Thesis and Clinic-related
Once you have created these directories in your local or
TEXMF tree, copy the directory you unpacked
from the archive file you downloaded to
TEXMF/bibtex/bst/hmcmath. You can also
cd to the destination directory within your
TEXMF tree and unpack the archives there.
Testing Your Installation
If you want to test your installation, you can try TeXing a document (such as the sample Clinic report/thesis) that uses the class or package. If it works, you're good!
If TeX can't find the class you installed, you may be able to
use some command-line tools to see whether TeX can find your new
files. Open a terminal or command window and
any directory except the one in which you installed the
files (your working directory is a good choice, but the test
should work in any directory). Run the command
The program should print the full path to your copy of the class file. If it doesn't, check to be sure that you have the same directory tree shown and that all the directory names are spelled exactly as shown.
Debugging Your Paths
Linux or Mac OS X systems include a
kpsepath command that can show you the full set of
paths that your TeX system will search when looking for a file.
[On a MikTeX system, all the search paths are visible in the
MikTeX Settings application.] So you might run
kpsepath -n latex tex
to show the full path that the
latex program will search
when looking for TeX source files (which includes class and
package files). The output will look something like the following
(note that we have split the output at the colons for clarity; the
actual output runs everything together on one line):
.: /home/students/username/.texlive2010/texmf-config/tex/latex//: /home/students/username/.texlive2010/texmf-var/tex/latex//: /home/students/username/texmf/tex/latex//: !!/shared/local/texlive/2010/texmf-config/tex/latex//: !!/shared/local/texlive/2010/texmf-var/tex/latex//: !!/shared/local/texlive/2010/texmf/tex/latex//: !!/shared/local/texlive/2010/../texmf-local/tex/latex//: !!/shared/local/texlive/2010/texmf-dist/tex/latex//: /home/students/username/.texlive2010/texmf-config/tex/generic//: /home/students/username/.texlive2010/texmf-var/tex/generic//: /home/students/username/texmf/tex/generic//: !!/shared/local/texlive/2010/texmf-config/tex/generic//: !!/shared/local/texlive/2010/texmf-var/tex/generic//: !!/shared/local/texlive/2010/texmf/tex/generic//: !!/shared/local/texlive/2010/../texmf-local/tex/generic//: !!/shared/local/texlive/2010/texmf-dist/tex/generic//: /home/students/username/.texlive2010/texmf-config/tex///: /home/students/username/.texlive2010/texmf-var/tex///: /home/students/username/texmf/tex///: !!/shared/local/texlive/2010/texmf-config/tex///: !!/shared/local/texlive/2010/texmf-var/tex///: !!/shared/local/texlive/2010/texmf/tex///: !!/shared/local/texlive/2010/../texmf-local/tex///: !!/shared/local/texlive/2010/texmf-dist/tex///
The output of this command may be a bit confusing. Each
colon-separated component is a directory that is searched by the
. at the top of the list is equivalent
to the current directory (which is why you can put package files
in your working directory and TeX will find them; it's also why we
recommended that you run the
kpsepath command from a
different directory when testing your installation).
The double exclamation marks (
!!) at the start of
some paths indicate that the program should look for a file called
ls-R at the root of that tree instead of searching
the filesystem for matching files. [These
are generated by the
texhash program, and are similar
to the output of the
ls command with the
-R (recursive) flag. Having the system's files be
indexed in this way makes TeX much faster.]
The doubled slashes at the end of the paths tell the search library to search subdirectories, not just the specified directory.
.texlive2010 directories in the user's home
directory are directories that TeX Live uses to store local
configuration information, such as when a user sets up a special
printer, a different default paper size, or has their own font
installations separate from the system.
In our example, the
latex program will first look
in the current working directory. Then it will look in its
user-level configuration and cache directories; then use the
ls-R files in
/shared/local/texlive/texmf-local/ to get a list of
possible completions in subdirectories of
/shared/local/texlive tree is available on all math
department Mac OS X and Linux systems, and is where the latest
version of the class files and other support files are kept).
After that, the program looks at the main system
TEXMF tree, again consulting the
After searching the
tex/latex trees, the program will look
for files in the
tex/generic subtree (files that can be used
by LaTeX or TeX), and then for files meant for use by TeX
If your local or personal
TEXMF tree doesn't
appear in the list, you may need to do some additional
configuration. Please consult the department's system
administrator or the
latex-l list for help.
If you're really curious about how TeX searches for files, you should read the article “A Directory Structure for TeX Files” and the “Kpathsea Library” manual.