summaryrefslogtreecommitdiff
path: root/support/latexmk/INSTALL
blob: e4783d9cb8f0df7fdf48a1f4e402d9eb1dce7111 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
            INSTALLING latexmk
            ==================
      (Version 4.75, 21 Sep. 2021)

            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 NOTE:  !!!!
===========================

If you have installed a modern distribution of TeX and friends, you
may find that latexmk is already installed on your computer.  This is
true for full installations of TeXLive 2009 or later on the operating
systems it supports.  (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 not include latexmk; in that case you
should be able to use your distribution's package manager to install
latexmk.  This is generally the recommended method; only use the
manual installation method below if you have a special need for it.
However, you should still examine the information on configuration
here and in the main documentation to get latexmk working exactly as
you want it.

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

If you are on MS-Windows and you are using TeXLive (2009, or later),
this distribution also includes a distribution of Perl sufficient to
run latexmk.pl, so you don't need to install Perl separately.  It also
includes an executable file latexmk.exe that runs latexmk.

In the case of MiKTeX, the other standard distribution for MS-Windows,
the main difference from TeXLive as regards latexmk is that you may
need to install a distribution of Perl. A standard default
installation of Perl should enable latexmk to work.

BUT, you may need to configure latexmk to


**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, you can install latexmk
simply by using the TeXLive package manager (that includes users of
MacTeX).  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.
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.  

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 should be in the
        system startup file, which on a UNIX-like operating system is any
        one of
        
           /opt/local/share/latexmk/LatexMk,
           /usr/local/share/latexmk/LatexMk,
           /usr/local/lib/latexmk/LatexMk,
           /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.  If you are installing latexmk as an ordinary user, the startup
        file is 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.

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 (your choice), and arrange for it to
    be invoked as a command.  (If you don't know how to do this, find out
    about "executable extension for perl on windows", by a web search.)

4.  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.  (Should be
    under Advanced system settings->Environment variables.)

5.  (Optional) Copy documentation file(s) to a suitable directory.  The
    only requirement on the directory is your convenience: 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.  

6.  You may need to reboot, or at least logoff and log back in, if you made
    any changes to PATH.

7.  Test out the installation at the command-line prompt:

    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 C:\latexmk\LatexMk.  (If
        this is not suitable for some reason, you'll need to change
        the latexmk.pl file where this filename appears.)

    b.  The user initialization file is .latexmkrc in the directory
        specified by the environment variable HOME.  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
=============

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 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.  The same goes for filenames and directory names with spaces in
    them.  Much software tends to interpret spaces as separators
    between different filenames or between filenames and other text.
    This can cause problems in some of the programs called by latexmk.
    It can also cause problems when latexmk parses a .log file to
    determine dependency information.  Latexmk does try to correctly
    treat filenames with spaces, as do current implementations of the
    TeX program.

3.  Beware also of files and directories whose names contain non-ASCII
    characters.  There are some tricky problems because of mismatches
    between character codings as used by different software and
    operating systems.  Latexmk tries to do its best, but problems can
    arise.  Often things work without trouble.

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