Enabling the LaTeX Master File on Mac OS X (and also some general Mac OS X LaTeX notes)

First of all, what is LaTeX? LaTeX is a typesetting tool. It allows you to type stuff and then formats it all together for you into a nice pretty document, usually in PDF. In this respect, it’s quite similar to Microsoft Word. The differences between the two, however, are in the way that you format the document.

Microsoft Word is visual. That is, if you want to adjust something, you usually have to do it manually. You drag a figure into the right spot, you drag the margin to the right width, or  you drag the paragraph into the correct location. Anyone who’s worked with Word for any amount of time though has encountered issues with formatting, especially when moving things around. You add a paragraph and boom, suddenly your pictures are all off of the edge of your screen!

LaTeX works differently because you specify the behaviour and the appearance of the document in addition to the text. LaTeX extensively uses templates to format your document so that you get a document that looks great no matter what you put into it. In this respect, it’s a little like HTML in that what you type into the screen doesn’t look like the final product – you need another program to make it look like the final result.

Anyway, this isn’t a LaTeX tutorial so to speak. What I really wanted to talk about are a couple of options for LaTeX on Mac OS X.


TeXShop is a simple GUI that allows you to easily type and compile your LaTeX.

For a long time, I used TexShop as my main LaTeX editor for the Mac. It’s a pretty nifty editor – it has good support for common LaTeX templates, it allows you to click back and forth between the rendered PDF and the position in your document to edit, and it’s very clean and simple to use. If you are looking to get up and running quickly, I highly recommend it.

The complete package for Mac is located here: http://www.tug.org/mactex

I am pretty sure that when you install MacTex, you get it by default, but if you don’t, you can get it here. http://pages.uoregon.edu/koch/texshop/


I bought TextMate for myself a few years ago but haven’t really used it for LaTeX until recently. I began to write my thesis, and it involved many files in the project. TextMate has a nice drawer that lists the files in the project and therefore is easier to manage than multiple TeXShop windows. For this reason, I began to move to TextMate.

However, TextMate needs a little bit of modification to make it work with the ease of TeXShop.

Textmate and Skim

Skim and TextMate. The project drawer is only one reason why TextMate is a strong editor for LaTeX.

PDFSync and TextMate

To get pdfsync working, which allows you to click between your rendered PDF file and the text file in which you’re editing that text, you should get Skim. Skim is an alternative PDF viewer that was originally designed to effectively export PDF annotations. There are a few options in the LaTeX bundle in TextMate to make pdfsync work with Skim, and an option in Skim to have it work with TextMate.

Download Skim here. It’s open-source.

The LaTeX Master file: Compile a Project from any File

One of the great things with LaTeX is the use of a “LaTeX Master File”. This allows you to specify what the “main file” is of your project so you don’t have to select it every time you want to compile your LaTeX project. In my example, the master file is “IrwinKwan_PhD_Dissertation.tex” and it imports the other files. There is an option in the LaTeX bundle of TextMate to set the master file but that isn’t enough.

In TexShop or any other Editor

To use a master file setting in any LaTeX project, put the following in every one of your .tex files:

%!TEX root=your_master_file.tex

where “your_master_file.tex” should be the actual name of the master file of your project. This works in TeXShop, in TextMate, or in any other text editor.

But, you can also do this in TextMate in a more specific matter as I’ve written below.

Setting the Master File in TextMate

What you need to do is to set an environment variable. Do that as follows.

The Textmate Info Box

Click on the "Info" box. Don't forget to de-select any files you might have selected first.

First, deselect files in the drawer view. To do this click on some white space below the drawer. If you need to, resize your window so you can reach it.

Second, click on the little “I” at the bottom of the drawer.

You’ll get a new window that asks for Environment Variables. Add a variable using the little “+” icon. The variable should be labelled TM_LATEX_MASTER. Give it the value equivalent to the full path of your LaTeX Master file. In my case, that’s “/Users/irwink/uvic/research/thesis/trunkIrwinKwan_PhD_Dissertation.tex”.

Setting variables in the variables window

Add the TM_LATEX_MASTER variable. The value is the full path to your master file.

Once you do that, you can then press Command-R and compile your project from any file you select (except for the master one, ironically). That was a real time-saver for me and allowed me to preview my changes from any file I was working on.


6 thoughts on “Enabling the LaTeX Master File on Mac OS X (and also some general Mac OS X LaTeX notes)

  1. flamingbike

    Hi Irwin, Thanks for the detailed post.

    After setting the TM_LATEX_MASTER variable, I’m not able to compile from other .tex files.

    At this point, I can compile the master file using command-R. However, I go to some other file in the project (for example, chap1.tex) and use command-R, the master file doesn’t compile. Instead, Textmate also adds a \begin{document} and \end{document} to the beginning of my chap1.tex file. Do you have any idea what’s the problem here?



    1. irwinhkwan Post author

      In your other TEX files, try putting this at the top:

      %!TEX root=your_master_file.tex

      Let me know how that works for you.

      I’m not certain about the \begin{document} and \end{document} for your chap1.tex file… if your master file is not chap1.tex then that definitely shouldn’t have the document tags there.

      1. flamingbike

        Thanks for the quick answer! I tried setting the master file by clicking Latex 2 > File Preferences > Set Master File, which successfully puts the line:

        %!TEX root=your_master_file.tex

        at the top.

        Didn’t work though, still doesn’t compile and the document tags are added again.

      2. flamingbike

        A friend suggested that different bundles have different environmental variables. Setting TM_PROJECT_MASTER to the path of the master file worked for me.

        FYI I’m using TM1.5 and compiling using the LaTeX 2 bundle.


  2. benfulcher

    Can also be handy to set your TM_LATEX_MASTER variable to a relative path, so if you copy the project to a new directory it doesn’t keep compiling from the old (absolute) path. Cheers!

  3. Martin Weiss Hansen

    You can also specify a LaTeX Master File in TexShop, and compile from any file. You made it sound like that’s only possible in TextMate. I’ve tried TextMate, and didn’t really like it for LaTeX. I really wish TexShop would have some kind of project settings, with a project drawer similar in function to that of TextMate.


Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s