% -*- latex -*- \documentclass{article} \newcommand{\UseLATEXVersion}{1.8.2} \newcommand{\SANDNumber}{SAND 2008-2743P} % This wonderful package allows hyphenation in tt fonts and hyphenation of % words with underscores in them. \usepackage[htt]{hyphenat} \usepackage{fancyvrb} \usepackage{color} \usepackage{xspace} \usepackage{hyperref} \hypersetup{pdftitle={UseLATEX.cmake: LaTeX Document Building Made Easy}} \hypersetup{pdfauthor={Kenneth Moreland}} % Simple commands that establish the font for various elements. \newcommand*{\textfile}[1]{\textsf{#1}} \newcommand*{\textprog}[1]{\textfile{#1}} \newcommand*{\textlatexpackage}[1]{\textsf{#1}} \newcommand*{\textcmake}[1]{\texttt{#1}} \newcommand*{\textcmakevar}[1]{\textcmake{#1}} \newcommand*{\textmaketarget}[1]{#1} \newcommand*{\textvar}[1]{\textit{#1}} \CustomVerbatimCommand{\textlatex}{Verb}{} % Simple commands that insert some standard text. \newcommand*{\UseLATEX}{\textfile{UseLATEX.cmake}\xspace} \newcommand*{\latex}{\LaTeX\xspace} \newcommand*{\bibtex}{\textsc{Bib}\TeX\xspace} \newcommand*{\miktex}{Mik\TeX\xspace} \ifdefined\synctex \renewcommand*{\synctex}{SyncTeX\xspace} \else \newcommand*{\synctex}{SyncTeX\xspace} \fi \newcommand*{\ald}{\textcmake{ADD\_LATEX\_DOCUMENT}\xspace} % Environments for listing CMake and other types of code. \definecolor{listingframecolor}{cmyk}{0,0,0,0.25} \CustomVerbatimEnvironment{CodeListing}{Verbatim}{ frame=single, rulecolor=\color{listingframecolor}, framesep=6pt} \newcommand*{\includeCodeListing}[2][]{\VerbatimInput[ frame=single, rulecolor=\color{listingframecolor}, framesep=4pt,#1]{#2}} \begin{document} \sloppy \title{UseLATEX.cmake: \latex Document Building Made Easy} \author{Kenneth Moreland} \date{Version \UseLATEXVersion} \maketitle \tableofcontents %----------------------------------------------------------------------------- \section{Description} \label{sec:Description} Compiling \latex files into readable documents is actually a very involved process. Although CMake comes with \textfile{FindLATEX.cmake}, it does nothing for you other than find the commands associated with \latex. I like using CMake to build my \latex documents, but creating targets to do it is actually a pain. Thus, I've compiled a bunch of macros that help me create targets in CMake into a file I call ``\UseLATEX.'' Here are some of the things \UseLATEX handles: \begin{itemize} \item Runs \latex multiple times to resolve links. \item Can run \textprog{bibtex}, \textprog{makeindex}, and \textprog{makeglossaries} to make bibliographies, indexes, and/or glossaries. \item Optionally runs configure on your \latex files to replace \textcmake{@\textvar{VARIABLE}@} with the equivalent CMake variable. \item Automatically finds png, jpeg, eps, and pdf files and converts them to formats \textprog{latex} and \textprog{pdflatex} understand. \end{itemize} %----------------------------------------------------------------------------- \section{Download} \label{sec:Download} \UseLATEX is currently posted to the CMake Wiki at \begin{quote} \href{http://public.kitware.com/Wiki/CMakeUserUseLATEX}{http://public.kitware.com/Wiki/CMakeUserUseLATEX}. \end{quote} %----------------------------------------------------------------------------- \section{Usage} \label{sec:Usage} Using \UseLATEX is easy. For a basic \latex file, simply include the file in your \textfile{CMakeLists.txt} and use the \ald command to make targets to build your document. For an example document in the file \textfile{MyDoc.tex}, you could establish a build with the following simple \textfile{CMakeLists.txt}. \begin{CodeListing} PROJECT(MyDoc NONE) INCLUDE(UseLATEX.cmake) ADD_LATEX_DOCUMENT(MyDoc.tex) \end{CodeListing} The \ald adds the following targets to create a readable document from \textfile{MyDoc.tex}: \begin{description} \item[\textmaketarget{dvi}] Creates \textfile{MyDoc.dvi}. \item[\textmaketarget{pdf}] Creates \textfile{MyDoc.pdf} using \textprog{pdflatex}. Requires the \textcmakevar{PDFLATEX\_COMPILER} CMake variable to be set. \item[\textmaketarget{ps}] Creates \textfile{MyDoc.ps}. Requires the \textcmakevar{DVIPS\_CONVERTER} CMake variable to be set. \item[\textmaketarget{safepdf}] Creates \textfile{MyDoc.pdf} from \textfile{MyDoc.ps} using \textprog{ps2pdf}. Many publishers prefer pdfs are created this way. Requires the \textcmakevar{PS2PDF\_CONVERTER} CMake variable to be set. \item[\textmaketarget{html}] Creates html pages. Requires the \textcmakevar{LATEX2HTML\_CONVERTER} CMake variable to be set. \item[\textmaketarget{clean}] To CMake's default \textmaketarget{clean} target, the numerous files that \latex often generates are added. \item[\textmaketarget{auxclean}] Deletes the auxiliary files from \latex, but not the generated input files. Sometimes \latex gets itself in a bad state where the auxiliary files need to be deleted to successfully build again, and this target does that without also deleting other build files (such as converted image files or files from unrelated targets in the same directory). \end{description} One caveat about using \UseLATEX is that you are required to do an out-of-source build. That is, CMake must be run in a directory other than the source directory. This is necessary as latex is very picky about file locations, and the relative locations of some generated or copied files can only be maintained if everything is copied to a separate directory structure. For more details and hints on workarounds, see the ``\hyperref[sec:Why_does_UseLATEX_have_to_copy_my_tex_files]{Why does \UseLATEX have to copy my tex files?}'' frequently asked question in Section~\ref{sec:Why_does_UseLATEX_have_to_copy_my_tex_files}. \subsection{Using a Bibliography} \label{sec:UsingABibliography} For any technical document, you will probably want to maintain a \bibtex database of papers you are referencing in the paper. You can incorporate your .bib files by adding them after the \textcmake{BIBFILES} argument to the \ald command. \begin{CodeListing} ADD_LATEX_DOCUMENT(MyDoc.tex BIBFILES MyDoc.bib) \end{CodeListing} This will automatically add targets to build your bib file and link it into your document. To use the \bibtex file in your \latex file, just do as you normally would with \textlatex|\cite| commands and bibliography commands: \begin{CodeListing} \bibliographystyle{plain} \bibliography{MyDoc} \end{CodeListing} You can list as many bibliography files as you like. \subsection{Incoporating Images} \label{sec:IncoporatingImages} To be honest, incorporating images into \latex documents can be a real pain. This is mostly because the format of the images needs to depend on the version of \latex you are running (\textprog{latex} vs. \textprog{pdflatex}). With these CMake macros, you only need to convert your raster graphics to png or jpeg format and your vector graphics to eps or pdf format. Place them all in a common directory (e.g. images) and then use the \textcmake{IMAGE\_DIRS} option to the \ald macro to point to them. \UseLATEX will take care of the rest. \begin{CodeListing} ADD_LATEX_DOCUMENT(MyDoc.tex BIBFILES MyDoc.bib IMAGE_DIRS images) \end{CodeListing} If you want to break up your image files in several different directories, you can do that, too. Simply provide multiple directories after the \textcmake{IMAGE\_DIRS} command. \begin{CodeListing} ADD_LATEX_DOCUMENT(MyDoc.tex BIBFILES MyDoc.bib IMAGE_DIRS icons figures) \end{CodeListing} Alternatively, you could list all of your image files separatly with the \textcmake{IMAGES} option. \begin{CodeListing} SET(MyDocImages logo.eps icons/next.png icons/previous.png figures/flowchart.eps figures/team.jpeg ) ADD_LATEX_DOCUMENT(MyDoc.tex IMAGES ${MyDocImages}) \end{CodeListing} %$ Both the \textcmake{IMAGE\_DIRS} and \textcmake{IMAGES} can be used together. The combined set of image files will be processed. If you wish to provide a separate eps file and pdf or png file, that is OK, too. \UseLATEX will handle that by copying over the correct file instead of converting. Once you establish the images directory, CMake will automatically find all files with known image extensions (currently eps, pdf, png, jpeg, and jpg) in it and add makefile targets to use ImageMagick's \textprog{convert} to convert the file times to those appropriate for the build. (One exception is that \textprog{ps2pdf} will be used when converting eps to pdf to get around a problem where ImageMagick drops the bounding box information.) If you do not have ImageMagick, you can get it for free from \href{http://www.imagemagick.org}{http://www.imagemagick.org}. CMake will also give you a \textcmakevar{LATEX\_SMALL\_IMAGES} option that, when on, will downsample raster images. This can help speed up building and viewing documents. It will also make the output image sizes smaller. Depending on what program is launched to build your \latex file (either \textprog{latex} or \textprog{pdflatex}, and \UseLATEX supports both), a particular format for your image is required. As stated, \UseLATEX handles the necessary conversions for you. However, you will not know in advance what file extension is used on the image. That is no problem. Simply leave out the file extension in the file name argument to \textlatex|\includegraphics| and \latex will find the file with the appropriate extension for you. Note that in order to ensure that the resulting image files are placed in the appropriate directory, you are required to give \emph{relative} paths for images and image directories. For example, \textcmake{IMAGE\_DIRS \$\{CMAKE\_CURRENT\_SOURCE\_DIR\}/images} will fail. Use \textcmake{IMAGE\_DIRS images} instead. \subsection{Create a PDF by Default} \label{sec:CreateAPDFByDefault} By default, when you use \ald and then run make with no arguments, the dvi file will be created. You have to specifically build the pdf target to use \textprog{pdflatex} to create a pdf file. However, oftentimes we want the pdf to be generated by default. To do that, simply use the \textcmake{DEFAULT\_PDF} option to \ald: \begin{CodeListing} ADD_LATEX_DOCUMENT(MyDoc.tex BIBFILES MyDoc.bib IMAGE_DIRS images DEFAULT_PDF) \end{CodeListing} If you still want to use the \textprog{latex} program to compile your documents but by default want to create pdf files (that is, build the safepdf target by default), then use the \textcmake{DEFAULT\_SAFEPDF} option to \ald: \begin{CodeListing} ADD_LATEX_DOCUMENT(MyDoc.tex BIBFILES MyDoc.bib IMAGE_DIRS images DEFAULT_SAFEPDF) \end{CodeListing} \subsection{\synctex-Enabled Editors} \label{sec:SynctexEnabledEditors} Some implementations of \latex compilers have a feature called \synctex that allows an editor or viewer to link between the compiled version of the document (such as a pdf) and the original \latex source code. The most common way to do this is to add \textprog{-synctex=1} to the \textprog{pdflatex} command. This will create a file named \textfile{\emph{$\langle$base-name$\rangle$}.synctex.gz} where each part of the final document points to the original \latex files. However, there is a problem. \UseLATEX copies all of the input \latex source files to an out-of-source build directory (see Section~\ref{sec:Why_does_UseLATEX_have_to_copy_my_tex_files} for more information on why). But the \latex compiler does not know that. Thus, the created \textfile{\emph{$\langle$base-name$\rangle$}.synctex.gz} will point to the temporary files in the build directory rather than your original source files. \UseLATEX can add commands to the make targets that ``correct'' the \textfile{\emph{$\langle$base-name$\rangle$}.synctex.gz}. To add these commands, simply turn on the \textcmakevar{LATEX\_USE\_SYNCTEX} in \textprog{ccmake} or equivalent CMake configuring tool. When this option is on, the \textprog{-synctex=1} argument is added to the \latex compile commands (settable with the \textcmakevar{LATEX\_SYNCTEX\_FLAGS} variable) and a command is added to targets that will find files in \textfile{\emph{$\langle$base-name$\rangle$}.synctex.gz} and change their paths to the original files in the source directory. \subsection{Building Multiple \latex Documents} \label{sec:BuldingMultipleLatexDocuments} The most common use for \UseLATEX is to build a single document, such as a paper you are working on. However, some use cases involve building several documents at one time. To do this, you must call \ald multiple times. However, if you do this, the dvi, pdf, etc. targets will be generated multiple times, and that is illegal in the current version of CMake.\footnote{CMake version 2.4 as of this writing.} To get around this, you need to mangle the names of the targets that \ald creates. To do this, use the \textcmake{MANGLE\_TARGET\_NAMES} option. \begin{CodeListing} ADD_LATEX_DOCUMENT(MyDoc1.tex MANGLE_TARGET_NAMES) ADD_LATEX_DOCUMENT(MyDoc2.tex MANGLE_TARGET_NAMES) \end{CodeListing} In the example above, the first call to \ald will create targets named \textmaketarget{MyDoc1\_dvi}, \textmaketarget{MyDoc1\_pdf}, \textmaketarget{MyDoc1\_ps}, etc. whereas the second call will create targets named \textmaketarget{MyDoc2\_*}. If you still want the simple, short targets to build all of the documents, you can add them yourself with custom targets that depend on the targets created by \ald \begin{CodeListing} ADD_CUSTOM_TARGET(dvi) ADD_DEPENDENCIES(MyDoc1_dvi MyDoc2_dvi) ADD_CUSTOM_TARGET(pdf) ADD_DEPENDENCIES(MyDoc1_pdf MyDoc2_pdf) ADD_CUSTOM_TARGET(ps) ADD_DEPENDENCIES(MyDoc1_ps MyDoc2_ps) \end{CodeListing} \subsection{Making an Index} \label{sec:MakingAnIndex} You can make an index in a \latex document by using the \textlatexpackage{makeidx} package. However, this package requires you to run the \textprog{makeindex} command. Simply add the \textcmake{USE\_INDEX} option anywhere in the \ald arguments, and \textprog{makeindex} will automatically be added to the build. \begin{CodeListing} ADD_LATEX_DOCUMENT(MyDoc.tex BIBFILES MyDoc.bib IMAGE_DIRS images USE_INDEX) \end{CodeListing} \subsection{Making a Glossary} \label{sec:MakingAGlossary} There are multiple ways to make a glossary in a \latex document, but the \textlatexpackage{glossaries} package provides one of the most convenient ways of doing so. Like the \textlatexpackage{makeidx} package, \textlatexpackage{glossaries} requires running \textprog{makeindex} or \textprog{xindy} for building auxiliary files. However, building the glossary files can be more complicated as there can be different sets of glossary files with different extensions. \UseLATEX will handle that for you. It does it in a way similar to the \textprog{makeglossary} command, but in a more portable way. Simply add the \textcmake{USE\_GLOSSARY} option anywhere in the \ald arguments, and the glossary creating will be handled for you. \begin{CodeListing} ADD_LATEX_DOCUMENT(MyDoc.tex BIBFILES MyDoc.bib IMAGE_DIRS images USE_GLOSSARY) \end{CodeListing} \subsection{Nomenclature Support} \label{sec:NomenclatureSupport} The \textlatexpackage{nomencl} package provides a mechanism to collect nomenclature and print it together in a single section. The \textlatexpackage{nomencl} behaves very similarly to \textlatexpackage{glossaries} (described in Section~\ref{sec:MakingAGlossary}) including running the \textprog{makeindex} command. However, the arguments to \textprog{makeindex} are a bit different (to avoid clashes with creating glossaries), and unfortunately \textlatexpackage{nomencl} provides no hints in the auxiliary file about it. Thus, \UseLATEX provides a special \textcmake{USE\_NOMENCL} option to \ald to add the necessary commands to build the nomenclature. \begin{CodeListing} ADD_LATEX_DOCUMENT(MyDoc.tex BIBFILES MyDoc.bib IMAGE_DIRS images USE_NOMENCL) \end{CodeListing} It should be noted that this feature only works with \textlatexpackage{nomencl} version 4.0 or later. The \textlatexpackage{nomencl} package changed how \textprog{makeindex} is called to make it compatible with indices and glossaries. The correct version of \textlatexpackage{nomencl} is easily identified as the one that uses the \textlatex|\makenomenclature| and \textlatex|\printnomenclature| commands (as opposed to the old \textlatex|\makeglossary| and \textlatex|\printglossary| commands). If you are using an older version of \textlatexpackage{nomencl}, you are best off to update for a number of reasons. \subsection{Multipart \latex Files} \label{sec:MultipartLatexFiles} Often, it is convenient to split a \latex document into multiple files and use the \latex \textlatex|\input| or \textlatex|\include| command to put them back together. To do this, all the files have to be located together. \UseLATEX can take care of that, too. Simply add the \textcmake{INPUTS} argument to \ald to copy these files along with the target tex file. Build dependencies to these files is also established. \begin{CodeListing} ADD_LATEX_DOCUMENT(MyDoc.tex INPUTS Chapter1.tex Chapter2.tex Chapter3.tex Chapter4.tex BIBFILES MyDoc.bib IMAGE_DIRS images USE_INDEX ) \end{CodeListing} As far as \UseLATEX is concerned, input files do not necessarily have to be tex files. For example, you might be including the contents of a text file into your document with the \textlatex|\VerbatimInput| command of the \textlatexpackage{fancyvrb} package. In fact, you could also add graphic files as inputs, but you would not get the extra conversion features described in Section~\ref{sec:IncoporatingImages}. \subsection{Configuring \latex Files} \label{sec:ConfiguringLatexFiles} Sometimes it is convenient to control the build options of your tex file with CMake variables. You can achieve this by using the \textcmake{CONFIGURE} argument to \ald. \begin{CodeListing} ADD_LATEX_DOCUMENT(MyDoc.tex INPUTS Chapter1.tex Chapter2.tex Chapter3.tex Chapter4.tex CONFIGURE MyDoc.tex BIBFILES MyDoc.bib IMAGE_DIRS images USE_INDEX ) \end{CodeListing} In the above example, in addition to copying \textfile{MyDoc.tex} to the binary directory, \UseLATEX will configure \textfile{MyDoc.tex}. That is, it will find all occurrences of \textcmake{@\textvar{VARIABLE}@} and replace that string with the current CMake variable \textcmakevar{\textvar{VARIABLE}}. With the \textcmake{CONFIGURE} argument you can list the target tex file (as shown above) as well as any other tex file listed in the \textcmake{INPUTS} argument. \begin{CodeListing} ADD_LATEX_DOCUMENT(MyDoc.tex INPUTS Ch1Config.tex Ch1.tex Ch2Config.tex Ch2.tex Ch3Config Ch3.tex CONFIGURE Ch1Config.tex Ch2Config.tex Ch3Config.tex BIBFILES MyDoc.bib IMAGE_DIRS images USE_INDEX ) \end{CodeListing} Be careful when using the \textcmake{CONFIGURE} option. Unfortunately, the \textlatex|@| symbol is used by \latex in some places. For example, when establishing a tabular environment, an \textlatex|@| is used to define the space between columns. If you use it more than once, then \UseLATEX will erroneously replace part of the definition of your columns for a macro (which is probably an empty string). This can be particularly troublesome to debug as \latex will give an error in a place that, in the original document, is legal. Hence, it is best to only configure tex files that contain very little text of the actual document and instead are mostly setup and options. \subsection{Identifying Dependent Files} \label{sec:IdentifyingDependentFiles} In some circumstances, CMake's configure mechanism is not sufficient for creating input files. Input \latex files might be auto-generated by any number of other mechanisms. If this is the case, simply add the appropriate CMake commands to generate the input files, and then add that file to the DEPENDS option of \ald. To help you build the CMake commands to place the generated files in the correct place, you can use the LATEX\_GET\_OUTPUT\_PATH convenience function to get the output path. \begin{CodeListing} LATEX_GET_OUTPUT_PATH(output_dir) ADD_CUSTOM_COMMAND(OUTPUT ${output_dir}/generated_file.tex COMMAND tex_file_generate_exe ARGS ${output_dir}/generated_file.tex ) ADD_LATEX_DOCUMENT(MyDoc.tex DEPENDS generated_file.tex) \end{CodeListing} %----------------------------------------------------------------------------- \section{Frequently Asked Questions} \label{sec:FrequentlyAskedQuestions} This section includes resolutions to common questions and issues concerning use of \UseLATEX and with \latex in general. \subsection{How do I process \latex files on Windows?} \label{sec:How_do_I_process_latex_files_on_Windows} I have successfully used two different ports of LaTeX for windows: the \href{http://www.cygwin.com/}{cygwin} port (\href{http://www.cygwin.com/}{http://www.cygwin.com/}) and the \href{http://www.miktex.org/}{\miktex} port (\href{http://www.miktex.org/}{http://www.miktex.org/}). If you use the cygwin port of \latex, you must also use the cygwin port of CMake, make, and ImageMagick. If you use the \miktex port of \latex, you must use the CMake from \href{http://www.cmake.org/HTML/Download.html}{http://www.cmake.org/HTML/Download.html}, the ImageMagick port from \href{http://www.imagemagick.org/script/index.php}{http://www.imagemagick.org/script/index.php}, and a native build tool like MSVC or the GNU make port at \href{http://unxutils.sourceforge.net/}{http://unxutils.sourceforge.net/}. \emph{Do not use the ``native'' CMake program with any cygwin programs or the cygwin CMake program with any non-cygwin programs.} This issue at hand is that the cygwin ports create and treat filenames differently then other windows programs.\footnote{If you are careful, you can use the cygwin version of make with the windows ports of CMake, \latex, and ImageMagick. It is an easy way around the problems described in Section~\ref{sec:Why_is_convert_failing_on_Windows}.} Also be aware that if you have images in your document, there are numerous problems that can occur on Windows with the ImageMagick \textprog{convert} program. See Section~\ref{sec:Why_is_convert_failing_on_Windows} for more information. \subsection{How do I process \latex files on Mac OS X?} \label{sec:How_do_I_process_latex_files_on_Mac_OS_X} Using \latex on Mac OS X is fairly straightforward because this OS is built on top of Unix. By using the Terminal program or X11 host, you can run \latex much like any other Unix variant. The only real issue is that \latex and some of the supporting programs like CMake and ImageMagick are not typically installed (whereas on Linux they often are). Most applications port fairly easily to Mac OS so long as you are willing to use them as typical Unix or X11 programs. To make things even easier, I recommend taking advantage of a Mac porting project to make this process even easier. \href{http://www.macports.org}{MacPorts} (\href{http://www.macports.org}{http://www.macports.org}) is a good tool providing a comprehensive set of tool ports including \latex, CMake, and ImageMagick. The \href{http://www.finkproject.org/}{fink project} and \href{http://finkcommander.sourceforge.net/}{FinkCommander} (\href{http://finkcommander.sourceforge.net/}{http://finkcommander.sourceforge.net/}) is a similar although less active project. \subsection{Why does \UseLATEX have to copy my tex files?} \label{sec:Why_does_UseLATEX_have_to_copy_my_tex_files} \UseLATEX cannot process your tex file without copying it. As explained in Section~\ref{sec:Usage}, \latex is very picky about file locations. The relative locations of files that your input files point to, and all but the most simple \latex files point to other files, must remain consistent. \UseLATEX will often have to modify at least one file either through configurations or image format and size conversions. When creating new files, \UseLATEX will have to copy either all of the files or none of the files. Since configuring and writing over an original file is unacceptable, \UseLATEX forces you to configure it such that \latex builds in a different directory than where you have placed the original. If you do not specify a seperate directory, you get an error like the following. \begin{CodeListing} CMake Error at UseLATEX.cmake:377 (MESSAGE): LaTeX files must be built out of source or you must set LATEX_OUTPUT_PATH. \end{CodeListing} The best way around this problem is do an ``out of source'' build, which is really the preferred method of using CMake in general. To do an out of source build, create a new build directory, go to that directory, and run cmake from there, pointing to the source directory. If for some reason an out of source build is not feasable or desireable, you can set the \textcmakevar{LATEX\_OUTPUT\_PATH} variable to a directory other than \textfile{.} (the local directory). If you are building a \latex document in the context of a larger project for which you wish to support in source builds, consider pragmatically setting the \textcmakevar{LATEX\_OUTPUT\_PATH} CMake cache variable from within your \textfile{CMakeLists.txt}. \subsection{Why is convert failing on Windows?} \label{sec:Why_is_convert_failing_on_Windows} Assuming that you have correctly downloaded and installed an appropriate version of ImageMagick (as specified in Section~\ref{sec:How_do_I_process_latex_files_on_Windows}), there are several other problems that users can run into the created build files attempt to run the \textprog{convert} program. A common error seen is \begin{CodeListing} Invalid Parameter - filename \end{CodeListing} This is probably because CMake has found the wrong \textprog{convert} program. Windows is installed with a program named \textprog{convert} in \textfile{\%SYSTEMROOT\%$\backslash$system32}. This \textprog{convert} program is used to change the filesystem type on a hard drive. Since the windows \textfile{convert} is in a system binary directory, it is usually found in the path before the installed ImageMagick \textfile{convert} program. (Don't get me started about the logic behind this.) Make sure that the \textcmakevar{IMAGEMAGICK\_CONVERT} CMake variable is pointing to the correct \textprog{convert} program. Another common error is that \textprog{convert} not finding a file that is clearly there. \begin{CodeListing} convert: unable to open image `filename' \end{CodeListing} If you notice that the drive letter is stripped off of the filename (i.e. \textfile{C:}), then you are probably mixing the Cygwin version of \textprog{convert} with the non-cygwin CMake. The cygwin version of \textprog{convert} uses the colon (:), as a directory separator for inputs. Thus, it assumes the output file name is really two input files separated by the colon. Switch to the non-cygwin port of ImageMagick to fix this. If you are using nmake, you may also see the following error: \begin{CodeListing} convert.exe: unable to open image `C:': Permission denied. \end{CodeListing} I don't know what causes this error, but it appears to have something to do with some strange behavior of nmake when quoting the convert executable. The easiest solution is to use a different build program (such as make or MSVC's IDE or a unix port of make). If anyone finds away around this problem, please contribute back. \subsection{How do I automate plot generation with command line programs?} \label{How_do_I_automate_plot_generation_with_command_line_programs} \latex is often used in conjunction with plotting programs that run on the command line like \textprog{gri} or \textprog{gnuplot}. Although there is no direct support for these programs in \UseLATEX, it is straightforward to use these programs. One way to use a plotting program is simply to run it yourself to generate the plot and then incorporate the image file into your \latex document as you would any other image file (see Section~\ref{sec:IncoporatingImages}). This the easiest way to incorporate these plots since it does not require additional CMake code. It also ensures consistency of how the plot looks (often the plots will look different if created on different platforms), and it provides the opportunity to edit the image to make it look better for publication. Another way to use these plotting programs is to automatically run them when building the \latex document. This is convenient if you frequently change the data you are plotting or if you are creating many plots. To automate running the plotting program build one or more targets to generate these files and then add these targets as \latex dependencies (see Section~\ref{sec:IdentifyingDependentFiles} for information on adding dependencies). Here is an example of creating the targets for converting a directory of \textprog{gri} files and incorporating the resulting files in a \latex document. \begin{CodeListing} # Set GRI executable SET(GRI_COMPILE "/usr/bin/gri") # Set the location of data files SET(DATA_DIR data) # Set the location of the directory for image files SET(IMAGE_DIR graphics) # Get a list of gri files FILE(GLOB_RECURSE GRI_FILES "*.gri") FOREACH(file ${GRI_FILES}) GET_FILENAME_COMPONENT(basename "${file}" NAME_WE) # Replace stings in gri file so data files can be found FILE(READ ${CMAKE_CURRENT_SOURCE_DIR}/${IMAGE_DIR}/${basename}.gri file_contents ) STRING(REPLACE "${DATA_DIR}" "${IMAGE_DIR}/${DATA_DIR}" changed_file_contents ${file_contents} ) FILE(WRITE ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${basename}.gri ${changed_file_contents} ) # Command to run gri IF(GRI_COMPILE) ADD_CUSTOM_COMMAND( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${basename}.eps DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${basename}.gri ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${DATA_DIR} COMMAND ${GRI_COMPILE} ARGS -output ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${basename}.eps ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${basename}.gri ) ENDIF(GRI_COMPILE) # Make a list of all gri files (for ADD_LATEX_DOCUMENT depend) SET(ALL_GRI_FILES ${ALL_GRI_FILES} ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${basename}.eps ) ENDFOREACH(file) # Copy over all data files needed to generate gri graphs ADD_CUSTOM_COMMAND( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${DATA_DIR} DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${IMAGE_DIR}/${DATA_DIR} COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/${IMAGE_DIR}/${DATA_DIR} ${CMAKE_CURRENT_BINARY_DIR}/${IMAGE_DIR}/${DATA_DIR} ) ADD_LATEX_DOCUMENT(MyDoc.tex IMAGE_DIRS ${IMAGE_DIR} DEPENDS ${ALL_GRI_FILES} ) \end{CodeListing} \subsection{Why does make stop after each image conversion?} \label{sec:Why_does_make_stop_after_each_image_conversion} There is a bug in the ImageMagick convert version 6.1.8 that inappropriatly returns a failure condition even when the image convert was successful. The problem might also occur in other ImageMagick versions. Try updating your installation of ImageMagick. \subsection{How do I resolve \textbackslash{}write 18 errors with \textlatexpackage{pstricks} or \textlatexpackage{pdftricks}?} \label{sec:How_do_I_resolve_write_18_errors_with_pstricks_or_pdftricks} A \textlatex|\write18| command is \latex's obtuse syntax for running a command on your system. Commands in the \textlatexpackage{pstricks} and \textlatexpackage{pdftricks} packages may need to run commands on your system to, for example, convert graphics from one format to another. Unfortunately, allowing \latex to run commands on your system can be considered a security issue. Some versions of \latex such as \miktex disable the feature by default. Thus, in order to use packages that rely on \textlatex|\write18|, you may have to enable the feature, typically with a command line option. For \miktex, this command line option is \textcmake{--enable-write18}. You can instruct \UseLATEX to pass any flag to \latex by adding it to the \textcmakevar{LATEX\_COMPILER\_FLAGS} CMake variable. One way to do this is through the CMake GUI. Simply go to the advanced variables, find \textcmakevar{LATEX\_COMPILER\_FLAGS}, and add \textcmake{--enable-write18} (or equivalent flag) to the list of arguments. You can also automatically add this flag by setting the flag in your \textfile{CMakeLists.txt} file. For example: \begin{CodeListing} SET(LATEX_COMPILER_FLAGS "-interaction=nonstopmode --enable-write18" CACHE STRING "Flags passed to latex." ) INCLUDE(UseLATEX.cmake) \end{CodeListing} The disadvantage of this latter approach is the reduction of portability. This addition could cause a failure for any \latex implementation that does not support the \textcmake{--enable-write18} flag (for which there are many). %----------------------------------------------------------------------------- \section{Acknowledgments} Thanks to all of the following contributors. \begin{description} \item[Arnout Boelens] Example of using gri in conjunction with \latex. \item[Mark de Wever] Fixes for interactions between the \textprog{makeglossaries} and \bibtex commands. \item[Alin Elena] Suggestions on removing dependence on makeglossaries command. \item[Myles English] Support for the \textlatexpackage{nomencl} package. \item[\O{}ystein S. Haaland] Support for making glossaries. \item[Sven Klomp] Help with \synctex support. \item[Thimo Langbehn] Support for pstricks with the \textcmake{--enable-write18} option. \item[Edwin van Leeuwen] Fix for a bug when copying \bibtex files. \item[Lukasz Lis] Workaround for problem with ImageMagick dropping the BoundingBox of eps files by using the \textprog{ps2pdf} program instead. \item[Eric Noulard] Support for any file extension on \latex input files. \item[Theodore Papadopoulo] \textcmake{DEPENDS} parameter for \ald and help in identifying some dependency issues. \item[Raymod Wan] \textcmake{DEFAULT\_SAFEPDF} option. \end{description} This work was primarily done at Sandia National Laboratories. Sandia is a multiprogram laboratory operated by Sandia Corporation, a Lockheed Martin Company, for the United States Department of Energy's National Nuclear Security Administration under contract DE-AC04-94AL85000. This document is released as technical report \SANDNumber. %----------------------------------------------------------------------------- \appendix \section{Sample CMakeLists.txt} \label{sec:SampleCMakeLists.txt} Following is a sample listing of CMakeLists.txt. In fact, it is the CMakeLists.txt that is used to build this document. \includeCodeListing{CMakeLists.txt} %% \section{UseLATEX.cmake Listing} %% \label{sec:UseLATEX.cmakeListing} %% \includeCodeListing[fontsize=\footnotesize]{UseLATEX.cmake} \end{document}