summaryrefslogtreecommitdiff
path: root/support/arara/doc/chapters/deploying.tex
blob: 25932f9f9d2c0db67051454f15cc73a4fd813c06 (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
% !TeX root = ../arara-manual.tex
\chapter{Deploying the tool}
\label{chap:deployingthetool}

As previously mentioned, \arara\ runs on top of a Java virtual machine, available on all major operating systems -- in some cases, you might need to install the proper virtual machine. This chapter provides detailed instructions on how to properly deploy the tool in your computer from either the official package available in our project repository or a personal build generated from source (as seen in Section~\ref{sec:compilingthetool}, on page~\pageref{sec:compilingthetool}).

\section{Directory structure}
\label{sec:directorystructure}

From the early development stages, our tool employs a very straightforward directory structure. In short, we provide the \abox[araracolour]{ARARA\_HOME} alias to the directory path in which the \rbox[araracolour]{arara.jar} Java archive file is located. This particular file is the heart and soul of our tool and dictates the default rule search path, which is a special directory named \abox[araracolour]{rules/} available from the same level. This directory contains all rules specified in the YAML format, as seen in Section~\ref{sec:rule}, on page~\pageref{sec:rule}. The structure overview is presented as follows.

\vspace{1em}

{\centering\begin{forest}
for tree={
  grow'=0,
  edge={araracolour},
  anchor=base west
},
forked edges,
[{\abox[araracolour]{ARARA\_HOME}}
  [{\rbox[araracolour]{arara.jar}}]
  [{\abox[araracolour]{rules/}},s sep=1mm
    [{\rbox[araracolour]{animate.yaml}}]
    [{\rbox[araracolour]{bib2gls.yaml}}]
    [{\color{araracolour}\ldots},no edge]
    [{\rbox[araracolour]{xetex.yaml}}]
    [{\rbox[araracolour]{xindy.yaml}}]
  ]
]
\end{forest}\par}

\vspace{1.4em}

Provided that this specific directory structure is honoured, the tool is ready for use off the shelf. In fact, the official \arara\ package available in the \href{https://gitlab.com/islandoftex/arara/-/releases}{release section} of our project repository. Once the package is properly downloaded, we simply need to extract it into a proper \abox[araracolour]{ARARA\_HOME} location.

\section{Defining a location}
\label{sec:definingalocation}

First and foremost, we need to obtain \rbox{arara-5.0.zip} from either our project repository at GitLab. As the name indicates, this is a compressed file format, so we need to extract it into a proper location. Run the following command in the terminal:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ unzip arara-5.0.zip
\end{codebox}

As a result of the previous command, we obtained a directory named \abox[araracolour]{arara} with the exact structure presented in Section~\ref{sec:directorystructure} in our working directory. Now we need to decide where \arara\ should reside in our system. For example, I usually deploy my tools inside the \abox[araracolour]{/opt/paulo} path, so I need to run the following command in the terminal (please note that my personal directory already has the proper permissions, so I do not need superuser privileges):

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ mv arara /opt/paulo/
\end{codebox}

The tool has found a comfortable home inside my system! Observe that the full path of the \abox[araracolour]{ARARA\_HOME} reference points out to \abox[araracolour]{/opt/paulo/arara} since this is my deployment location of choice. The resulting structure overview, from the root directory, is presented as follows:

\vspace{1em}

{\centering\begin{forest}
for tree={
  grow'=0,
  edge={araracolour},
  anchor=base west
},
forked edges,
[{\abox[araracolour]{/}},s sep=1mm
  [{\abox[araracolour]{bin/}}]
  [{\abox[araracolour]{boot/}}]
  [{\color{araracolour}\ldots},no edge]
  [{\abox[araracolour]{opt/}},s sep=1mm
    [{\abox[araracolour]{paulo/}}
      [{\abox[araracolour]{arara/}}
        [{\rbox[araracolour]{arara.jar}}]
        [{\abox[araracolour]{rules/}},s sep=1mm
          [{\rbox[araracolour]{animate.yaml}}]
          [{\rbox[araracolour]{bib2gls.yaml}}]
          [{\color{araracolour}\ldots},no edge]
          [{\rbox[araracolour]{xetex.yaml}}]
          [{\rbox[araracolour]{xindy.yaml}}]
        ]
      ]
    ]
    [{\color{araracolour}\ldots},no edge]
    [{\abox[araracolour]{texbin/}}]
  ]
  [{\color{araracolour}\ldots},no edge]
  [{\abox[araracolour]{usr/}}]
  [{\abox[araracolour]{var/}}]
]
\end{forest}\par}

\vspace{1.4em}

If the tool was built from source (as indicated in Section~\ref{sec:compilingthetool}, on page~\pageref{sec:compilingthetool}), make sure to construct the provided directory structure previously presented. We can test the deployment by running the following command in the terminal (please note the full path):

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ java -jar /opt/paulo/arara/arara.jar
  __ _ _ __ __ _ _ __ __ _
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

Usage: arara [OPTIONS] [file]...

Options:
  -l, --log                        Generate a log output
  -v, --verbose / -s, --silent     Print the command output
  -n, --dry-run                    Go through all the motions of running a
                                   command, but with no actual calls
  -H, --header                     Extract directives only in the file header
  -t, --timeout INT                Set the execution timeout (in milliseconds)
  -L, --language TEXT              Set the application language
  -m, --max-loops INT              Set the maximum number of loops (> 0)
  -p, --preamble TEXT              Set the file preamble based on the
                                   configuration file
  -d, --working-directory DIRECTORY
                                   Set the working directory for all tools
  -V, --version                    Show the version and exit
  -h, --help                       Show this message and exit

Arguments:
  file  The file(s) to evaluate and process
\end{codebox}

Please observe that, provided that the underlying operating system has an appropriate Java virtual machine installed, \arara\ can be used as a portable, standalone application. Portable applications can be stored on any data storage device, including external devices such as USB drives and floppy disks.

\section{Tool wrapping}
\label{sec:toolwrapping}

\arara\ is now properly deployed in our system, but we still need to provide the full path of \rbox{arara.jar} to the Java virtual machine in order to make our tool work. This section provides three approaches regarding the creation of a \emph{wrapper}, a shell feature that embeds a system command or utility, that accepts and passes a set of parameters to that command.

\begin{description}
\item[shell alias] An \emph{alias} is a command available in various shells which enables a replacement of a word by another string. It is mainly used for abbreviating a system command, or for adding default arguments to a regularly used command. In order to create a shell alias for our tool, open \rbox{.bashrc} (a script that is executed whenever a new terminal session starts in interactive mode) in your favourite editor and add the following line, preferably at the end:

\begin{codebox}{Source code}{teal}{\icnote}{white}
alias arara='java -jar /opt/paulo/arara/arara.jar'
\end{codebox}

Save the file and restart your terminal. It is important to observe that the given full path must be properly quoted if it contains spaces. There is no need to provide explicit parameters, as an alias simply acts as an inline string replacement.

\item[shell function] A \emph{shell function} is, as the name suggests, a subroutine, a code block that implements a set of operations as a means to performs a specified task. In order to create a shell function for our tool, open \rbox{.bashrc} (a script that is executed whenever a new terminal session starts in interactive mode) in your favourite editor and add the following line, preferably at the end:

\begin{codebox}{Source code}{teal}{\icnote}{white}
arara() {
    java -jar /opt/paulo/arara/arara.jar "$@"
}
\end{codebox}

Save the file and restart your terminal. It is important to observe that the given full path must be properly quoted if it contains spaces. Note that the \rbox{\$@} symbol used in the function body represents a special shell variable that stores all the actual parameters in a list of strings.

\begin{messagebox}{Alias or function?}{attentioncolour}{\icattention}{black}
In general, an alias should effectively not do more than change the default options of a command, as it constitutes a mere string replacement. A function should be used when you need to do something more complex than an alias. In our particular case, as the underlying logic is pretty straightforward, both approaches are valid.
\end{messagebox}

\item[script file] A \emph{script} is a computer program designed to be run by an interpreter. In our context, the script merely sets up the environment and runs a system command. In order to provide a script for our tool, open your favourite editor and create the following file called \rbox{arara} (no extension):

\begin{ncodebox}{Source file}{teal}{\icnote}{white}{arara}
#!/bin/bash
jarpath=/opt/paulo/arara/arara.jar
java -jar "$jarpath" "$@"
\end{ncodebox}

It is important to observe that the given full path must be properly quoted if it contains spaces. Note that the \rbox{\$@} symbol used in the script body represents a special shell variable that stores all the actual parameters in a list of strings. This script file will act as the entry point for our tool. Now, we need to make it executable (i.e, set the corresponding execute permission) by running the following command in the terminal:

\begin{codebox}{Source code}{teal}{\icnote}{white}
$ chmod +x arara
\end{codebox}

Now we need to move this newly executable script file to one of the directories set forth in the \abox[araracolour]{PATH} environment variable, where executable commands are located. For illustrative purposes only, let us move the script file to the \abox[araracolour]{/usr/local/bin/} directory, a location originally designed for programs that a normal user may run. Run the following command in the terminal (note the need for superuser privileges):

\begin{codebox}{Source code}{teal}{\icnote}{white}
$ sudo mv arara /usr/local/bin/
\end{codebox}

Alternatively, the script can be placed inside a special directory named \abox[araracolour]{bin/} from the home directory of the current user, which is usually added by default to the system path. Observe that, in this particular case, superuser privileges are not required, as the operation is kept at the current user level. Run the following command in the terminal instead (please note that the \rbox{\textasciitilde} symbol is a shell feature called \href{http://www.gnu.org/software/bash/manual/html_node/Tilde-Expansion.html}{tilde expansion} and refers to the home directory of the current user):

\begin{codebox}{Source code}{teal}{\icnote}{white}
$ mv arara ~/bin/
\end{codebox}

There is no need to restart your terminal, as the reference becomes available as soon as it is moved to the new location. Note that a shell script can provide a convenient variation of a system command where special environment settings, command options, or post-processing apply automatically, but in a way that allows the new script to still act as a fully normal Unix command.
\end{description}

Regardless of the adopted approach, there should be an \rbox{arara} wrapper available as an actual Unix command in your shell session. In order to test the wrapper, run the following command in the terminal:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ arara
  __ _ _ __ __ _ _ __ __ _
 / _` | '__/ _` | '__/ _` |
| (_| | | | (_| | | | (_| |
 \__,_|_|  \__,_|_|  \__,_|

Usage: arara [OPTIONS] [file]...

Options:
  -l, --log                        Generate a log output
  -v, --verbose / -s, --silent     Print the command output
  -n, --dry-run                    Go through all the motions of running a
                                   command, but with no actual calls
  -H, --header                     Extract directives only in the file header
  -t, --timeout INT                Set the execution timeout (in milliseconds)
  -L, --language TEXT              Set the application language
  -m, --max-loops INT              Set the maximum number of loops (> 0)
  -p, --preamble TEXT              Set the file preamble based on the
                                   configuration file
  -d, --working-directory DIRECTORY
                                   Set the working directory for all tools
  -V, --version                    Show the version and exit
  -h, --help                       Show this message and exit

Arguments:
  file  The file(s) to evaluate and process
\end{codebox}

It is important to observe that the wrapper initiative presented in this section might cause a potential name clash with existing \TeX\ Live or MiK\TeX\ binaries and symbolic links. In this particular scenario, make sure to inspect the command location as a means to ensure a correct execution. To this end, run the following command in the terminal:

\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ which arara
/usr/local/bin/arara
\end{codebox}

The \rbox{which} command shows the full path of the executable name provided as parameter. This particular utility does this by searching for an executable or script in the directories listed in the \abox[araracolour]{PATH} environment variable. Be mindful that aliases and shell functions are listed as well.