INSTALLING latexmk ================== (Version 4.77, 17 Mar. 2022) John Collins Physics Department Penn State University 104 Davey Lab, Box 208 University Park PA 16802 U.S.A. http://www.personal.psu.edu/jcc8/ http://www.personal.psu.edu/jcc8/latexmk/ username jcc8 at node psu.edu Latexmk is a "make" tool for building latex documents. It runs latex and/or pdflatex the appropriate number of times to resolve cross references etc, and, if necessary, it also runs makeindex and/or bibtex (or biber) and other programs when appropriate. Then it can make postscript or pdf files, print the result or preview it, as requested. It can also be set to run continuously with a previewer; the latex program, etc, are then rerun whenever one of the source files is modified. Latexmk automatically determines file dependencies from the LaTeX .log and .fls files. Latexmk can be installed and used on UNIX (including LINUX and OS-X), and MS Windows (tested under WinXP and some later versions). It can presumably be used on other systems with suitable customization. On all systems, the prequisites are a. A working installation of Perl. (See http://www.cpan.org/ if you don't have one. Modern UNIX-like systems, particularly linux and OS-X, often have perl installed by default. As for MSWindows, the TeXLive distribution (2009 or later) includes Perl, and in the default configuration also includes latexmk.) b. A working installation of TeX and LaTeX. (See http://www.ctan.org/ if you don't have one.) c. In addition, the installation of TeX and LaTex should, of course, contain the packages etc that are needed for your specific documents to be compiled and processed. !!!! IMPORTANT NOTES: !!!! ============================ 1. If you have installed a distribution of TeX and friends, you will probably find that latexmk is already installed on your computer. This applies to both the TeXLive and the MiKTeX distributions (Note that MacTeX on OS-X incorporates TeXLive, so anything said about TeXLive also applies to MacTeX.) If you have only installed a subset of packages, e.g., because you installed BasicTeX, then the subset may or may not include latexmk; in that case you should be able to use your distribution's package manager to install latexmk. Having latexmk installed by a TeX distribution is normally the recommended way to be able to use latexmk. 2. The only extra requirement beyond having latexmk installed is to have an installation of Perl. See above. 3. You will normally need to use the manual installation method below if you have a special need for it. However, you should still examine the information on configuration below and in the main documentation to get latexmk working exactly as you want it. 4. You can test whether latexmk is already properly installed by trying the command "latexmk -v" from the command line. If this succeeds, then latexmk is already installed and will report its version number. Otherwise, if you are using TeXLive or MacTeX, then you can simply use its package manager to get latexmk installed, the same as for any other missing package. BUT, you may need to configure latexmk to adjust its behavior to suit your needs. See item 6 below, as well as the full documentation, for further information. **Manual** installation on UNIX/LINUX/OS-X ========================================== (Power users can modify these as appropriate, of course.) NOTE: If you are using TeXLive 2009 or later, or a moderately recent version of MiKTeX, you can install latexmk simply by using the TeXLive package manager (that includes users of MacTeX). In fact, depending on how much of TeXLive or MiKTeX you have already installed, latexmk may already have been installed. In that case you don't normally need to bother with the manual installation explained below. Still you may need to examine the configuration instructions see item 6. 1. Make sure you have working installations of Perl and TeX/LaTeX. 2. Put the file latexmk.pl in a directory for executable files. For example, for a system-wide installation, you could put it in /usr/local/bin. But if you are an ordinary user, you can put the file somewhere where you have access, and ensure that the PATH environment variable includes the directory where latexmk is installed. If you are using MS-Windows, go to the corresponding items in the instructions for Windows. 3. Rename this file to latexmk. 4. Make sure latexmk is executable, e.g., by using chmod suitably. [Special case, which you probably don't have to be concerned with: You **may** also find it necessary to change the first line of the script so that perl can be found to execute latexmk. Currently the first line is #!/usr/bin/env perl, which uses the program /usr/bin/env to find perl, provided only that the perl executable can be found in the PATH for executables. This insulates latexmk from the fact that the Perl executable has a system-dependent location. The program /usr/bin/env is present on almost all modern UNIX-type systems, including linux and macOS.] 5. (Optional) Copy the file latexmk.1 to an appropriate directory for man pages, e.g., /usr/local/man/man1/. Alternatively, or in addition, put the file latexmk.pdf in a suitable place for pdf files for documentation. 6. Check whether the commands used by latexmk for executing latex etc are correct or need changes. See below for how to do this in a configuration file, and the documentation for further information. The commands you particularly have to worry about are those for previewing files (set by the variables $pdf_previewer, $ps_previewer, and $dvi_previwer), and most importantly $pscmd, and its associated variable $pid_position --- see below. The command $pscmd is the least obvious: it runs the command ps and is used in preview_continuous_mode to determine whether a previewer is already running. The format of the output of ps is highly system dependent. Latexmk should get it right under LINUX and macOS. To know what the current settings are, run latexmk --commands from the command line. If latexmk does not get one of more of these commands correct, put an override in a startup file: a. For a system-wide installation, the correction can be in the system startup file, which on a UNIX-like operating system is any one of /etc/LatexMk, /opt/local/share/latexmk/LatexMk, /usr/local/share/latexmk/LatexMk, /usr/local/lib/latexmk/LatexMk, /etc/latexmkrc, /opt/local/share/latexmk/latexmkrc, /usr/local/share/latexmk/latexmkrc, /usr/local/lib/latexmk/latexmkrc. (You get to choose which, but only one. If none of these directories is appropriate you'll need to modify latexmk.pl.) Those directories apply to Unix-like operating systems (including linux and macOS). On MS-Windows, the system start-up file is one of C:\latexmk\LatexMk C:\latexmk\latexmkrc (If you happen to use Cygwin, latexmk combines both the MS-Windows and the Unix possibilities.) b. You can also/instead put the configuration lines in the user startup file, which is the file .latexmkrc in your home directory. (Under normal circumstances, latexmk's definition of home directory under Unix-like operating systems is the usual one, i.e., the value in the environment variable HOME. Under MS-Windows, a user's home directory is normally the directory of the user profile, as given in the environment variable USERPROFILE. In general, latexmk takes a user's home directory to be the directory specified in the first of the environment variables HOME and USERPROFILE that is non-empty.) The startup files are written in Perl, so possible overrides are like $latex = 'unusual_program_to_run_instead_of_normal_latex %O %S'; for changing the program to run latex, and $pscmd = 'ps -aeg'; $pid_position = 1; for the ps command. Here, $pid_position = 1 indicates that the process ID number is in the first column of the output of the command ps. See the latexmk documentation for more details. 7. If you need any modifications on the commands for running previewers, like gv, note that prefixing a command by start, as in $ps_previewer = 'start gv -watch %O %S'; ensures that the command is run detached, as is normally appropriate for a previewer. (In the examples above, there appear the strings %O and %S. See the documenation for details. They are placeholders used when latexmk constructs the command line. %O denotes any options latexmk wants to add to the command invocation, and %S denotes the source file.) 8. You may also want to change the defaults on what kinds of output file latexmk makes. By default latexmk makes dvi files, but not postscript or pdf files. If you (or people on your system) generally make pdf files using pdflatex, it would be a good idea to put the following in an appropriate initialization file: $pdf_mode = 1; $postscript_mode = 0; $dvi_mode = 0; See step 6 for the locations of the initialization/configuration files where you should put these lines. **Manual** Installation on MS-Windows ===================================== (Power users can modify these as appropriate.) NOTE: If you are using TeXLive 2009 or later, you can install latexmk simply by using the TeXLive package manager. In fact, depending on how much of TeXLive you have already installed, latexmk may already have been installed. In that case you don't normally need to bother with the manual installation explained below. Similarly if you have MiKTeX, you can install latexmk by using MiKTeX's package manager. But to allow latexmk to work, you will also need to install a distribution of Perl if you haven't done so already. In either of these cases you don't normally need to bother with the manual installation explained below. Still you may need to examine the configuration instructions see item 6. 1. Make sure you have working installations of Perl and TeX/LaTeX, complete with viewers for dvi, postscript and/or pdf files. You will also need whatever packages your document needs. 2. If necessary, unpack the latexmk distribution. 3. **Difference compared with UNIX-type systems**: Copy the file latexmk.pl to a suitable directory and arrange for it to be invoked as a command. See the following sentences for what "suitable directory" means. One way to ensure that you can invoke the latexmk command is to also put the file latexmk.cmd in the same directory, and then follow the next instructions: If the directory in the previous step is NOT already in the search path for executable files, arrange for this, by adjusting the environment variable PATH suitably. In Windows, there is a Control Panel setting for this. (It should be under Advanced system settings->Environment variables.) Log out and back in to make sure the changed setting gets used. Note: Each of TeXLive and MiKTeX make a suitable change to the PATH environment variable, so that all the programs they install are usable, including latexmk. 4. You may need to reboot, or at least logoff and log back in, if you made any changes to PATH. 5. Concerning invocation of latexmk: See later items. 6. (Optional) Copy documentation file(s) to a suitable directory. The only requirement on the directory is your convenience: i.e., some convenient place to look up documentation. The relevant files are latexmk.txt which is a pure ASCII text file, and latexmk.pdf which is a postscript file. 7. Test out the installation at the command-line prompt (cmd.exe or Power Shell): a. First do latexmk --version This should show you the version number of latexmk. If this works latexmk is accessible. If not, you will have to figure out what did not work in the previous steps. b. Then change to a directory where you have a good LaTeX file. Suppose the file is paper.tex. Delete any pre-existing dvi file, so that latexmk is forced to remake the output files. The following commands will check out the main features of latexmk: latexmk paper latexmk -pv paper latexmk -pv -ps paper The first command will create the dvi file, running latex a suitable number of times, and additionally running bibtex and makeindex, but only if needed. The second command will open a viewer of the dvi file. The third command will create a postscript file, and then open a viewer for it. c. If the above works, you are done. If not, you will have to figure out what is wrong, and correct it. FIRST, READ THE DOCUMENTATION! The normal problems are that the names for the commands used by latexmk are incorrect for your system, or they are not present on your system. See the next item for how to customize latexmk. Also LOOK AT THE SECTION NAMED "TRICKY POINTS" below to see some hints. 8. If the commands used by latexmk are incorrect, see the UNIX installation instructions for what to do. The only changes needed from the UNIX instructions are: a. The system initialization file is either C:\latexmk\LatexMk or C:\latexmk\latexmkrc. (If these is not suitable for some reason, you'll need to change the latexmk.pl file where this filename appears. But normally it's easier to change the user latexmkrc file --- see the next item.) b. The user initialization file is .latexmkrc in the directory specified by the environment variable HOME, if that happens to be defined, which it normally isn't. If there is no HOME variable, then the file is in the directory specified by the environment variable USERPROFILE, which should have been set by the MS-Windows operating system at login. Other systems ============= For other systems you are on your own. The instructions for UNIX/LINUX and MS-Windows should help you to see what to do. Let me know (username jcc8 at node psu.edu) what happens, so that I can update these instructions and possibly latexmk as well. Tricky points ============= (These aren't so much issues about installation as about use of latexmk.) 1. BEWARE of filenames with double extensions, for example, two.part.tex. The behavior of TeX-related software is not consistent in this situation. You may, for example, find a log file named two.log or two.part.log, depending on which version of which implementation of TeX/LaTeX you use. Naturally, there is a possibility in this situation that latexmk will get confused, and not recognize, for example, that a dvi or other file has been generated. Latexmk has configuration variables to deal with some of the possibilities, so you could try playing with them --- see the code. But it general, it is best to avoid such double extensions: they make your files non-portable. Do something like two-part.tex or two_part.tex instead. 2. Filenames and directory names with spaces in them can potentially cause problems. Much software tends to interpret spaces as separators between different filenames or between filenames and other text. This coul cause problems in some of the programs called by latexmk. Even so, file and directory names containing spaces generally cause no problems in both latexmk and the programs it calls. 3. Non-ASCII characters in file and directory names: In the current version of latexmk and current TeXLive and MiKTeX, these are generally handled correctly, particular on linux and macOS systems. But it is worth being aware there is a potential for problems: (a) Default installations of MS-Windows do not make all Unicode characters in filenames available to Perl and hence latexmk. (b) Some annoying issues may arise if you transfer files from a macOS HFS+ volume to a volume used by another operating system for use with that OS. These problems concern different ways of normalizing filenames containing accented characters, and may entail renaming the transferred files. 4. If you need to remake documentation files, e.g., latexmk.pdf or latexmk.txt, from the man page file latexmk.1, the following commands work (on my linux and OS-X systems at least): Postscript file from latexmk.1: groff -Tps -man-old -rcR=0 latexmk.1 > latexmk.ps Pdf file from postscript: ps2pdf latexmk.ps latexmk.pdf Text file: groff -Tascii -man-old -rcR=0 latexmk.1 > latexmk.txt Credits ======= The original version of this program was called 'go', and written by David Musliner. That version is Copyright 1992 by David J. Musliner and The University of Michigan. Version 2 was modified by Evan McLean. The current version is by John Collins (username jcc8 at node psu.edu) -- other contact details at the top. It is copyright 1998-2022 by John Collins, and the previous authors; see the copyright notice in the latexmk.pl file, which gives permission to use, copy, modify, and distribute this software and its documentation under the terms of the GNU Public License v. 2.