Installing Classes and Packages

The mathematics department's computers have the hmcclinic, 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 “TEXMF 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.

TEXMF Trees

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.

Local TEXMF Trees

Local 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 following table:

Personal TEXMF Trees

Personal 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 system administrators.

For Unix-like systems such as Linux and Mac OS X, personal TEXMF 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:

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 System standard.

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 to the 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:

1. The class and its support files, which include the HMC logo (and seal, for some classes) and some configuration files; and,
2. The hmcmath.bst bibliography style file. [There is also a hmcmathannote.bst file that provides an annotated version of the hmcmath bibliography 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 department computer.

Downloading the Class and Support Files

You can download the department's classes from our LaTeX classes pages. The classes also have their own pages: HMC Clinic Report Class and HMC Thesis Class.

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 subdirectories in /shared/local/texlive/texmf-local/tex/latex/. Copy the files from the directories without version numbers to get the latest version (e.g., hmcclinic rather than hmcclinic-3.2).

The latest hmcmath bibliography-style files can be found in /shared/local/texlive/texmf-local/texmf/bibtex/bst/hmcmath/.

Installing the Class and Support Files

As noted, there are many possible subdirectories for local and personal 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/
              ...

Once you have created these directories in your local or personal TEXMF tree, copy the directory you unpacked from the archive file you downloaded to TEXMF/tex/latex/ and hmcmath.bst 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 cd into 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

kpsewhich hmcclinic.cls

or

kpsewhich hmcthesis.cls

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 program. 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 kpsewhich/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 ls-R files 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.

The .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/texmf-local/tex/latex/ (the /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 ls-R file.

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 alone.

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.

More Information

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.

Copyright © 2012 Harvey Mudd College

Harvey Mudd College is a member of The Claremont Colleges
301 Platt Boulevard, Claremont, CA 91711 • (909) 621-8000 • Map + Directions