summaryrefslogtreecommitdiff
path: root/support/arara/doc/chapters/building.tex
diff options
context:
space:
mode:
Diffstat (limited to 'support/arara/doc/chapters/building.tex')
-rw-r--r--support/arara/doc/chapters/building.tex53
1 files changed, 31 insertions, 22 deletions
diff --git a/support/arara/doc/chapters/building.tex b/support/arara/doc/chapters/building.tex
index 9c9b27c124..4f894f01b7 100644
--- a/support/arara/doc/chapters/building.tex
+++ b/support/arara/doc/chapters/building.tex
@@ -2,7 +2,7 @@
\chapter{Building from source}
\label{chap:buildingfromsource}
-\arara\ is a Kotlin and Java application licensed under the \href{http://www.opensource.org/licenses/bsd-license.php}{New BSD License}, a verified GPL-compatible free software license, and the source code is available in the project repository at \href{https://gitlab.com/islandoftex/arara}{GitLab}. This chapter provides detailed instructions on how to build our tool from source.
+\arara\ is a Kotlin application licensed under the \href{http://www.opensource.org/licenses/bsd-license.php}{New BSD License}, a verified GPL-compatible free software license, and the source code is available in the project repository at \href{https://gitlab.com/islandoftex/arara}{GitLab}. This chapter provides detailed instructions on how to build our tool from source.
\section{Requirements}
\label{sec:requirements}
@@ -14,12 +14,12 @@ In order to build our tool from source, we need to ensure that our development e
\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ git --version
-git version 2.17.1
+git version 2.29.2
\end{codebox}
Please refer to the \rbox{git} \href{https://git-scm.com/}{project website} in order to obtain specific installation instructions for your operating system. In general, most recent Unix systems have \rbox{git} installed out of the shelf.
-\item Our tool is written in the Java programming language, so we need a proper Java Development Kit, a collection of programming tools for the Java platform. Our source code is known to be compliant with several vendors, including Oracle, OpenJDK, and Azul Systems. In order to check if your operating system has the proper tools, run the following command in the terminal (version numbers might vary):
+\item Our tool is written in the Kotlin programming language, so we need a proper Java Development Kit, a collection of programming tools for the Java platform. Our source code is known to be compliant with several vendors, including Oracle, OpenJDK, and Azul Systems. In order to check if your operating system has the proper tools, run the following command in the terminal (version numbers might vary):
\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ javac -version
@@ -28,7 +28,7 @@ javac 1.8.0_171
The previous command, as the name suggests, refers to the \rbox{javac} tool, which is the Java compiler itself. The most common Java Development Kit out there is from \href{http://www.oracle.com/technetwork/java/javase/downloads/index.html}{Oracle}. However, several Linux distributions (as well as some developers, yours truly included) favour the OpenJDK vendor, so your mileage may vary. Please refer to the corresponding website of the vendor of your choice in order to obtain specific installation instructions for your operating system.
-\item As a means to provide a straightforward and simplified compilation workflow, \arara\ relies on Gradle, a software project management and comprehension tool. Gradle is a build tool just like arara with a much more comprehensive build framework to provide support for the JVM ecosystem. In order to check if \rbox{gradle}, the Gradle binary, is available in your operating system, run the following command in the terminal (version numbers might vary):
+\item As a means to provide a straightforward and simplified compilation workflow, \arara\ relies on Gradle, a software project management and comprehension tool. Gradle is a build tool just like ours with a much more comprehensive build framework to provide support for the JVM ecosystem. In order to check if \rbox{gradle}, the Gradle binary, is available in your operating system, run the following command in the terminal (version numbers might vary):
\begin{codebox}{Terminal}{teal}{\icnote}{white}
$ gradle --version
@@ -41,7 +41,8 @@ Revision: <unknown>
Kotlin: 1.3.50
Groovy: 2.5.8
-Ant: Apache Ant(TM) version 1.10.7 compiled on September 1 2019
+Ant: Apache Ant(TM) version 1.10.7 compiled
+ on September 1 2019
JVM: 1.8.0_232 (Oracle Corporation 25.232-b09)
OS: Linux 5.5.0-1-MANJARO amd64
\end{codebox}
@@ -101,7 +102,7 @@ Great, we are in the correct location! From the previous output, let us inspect
$ gradle build
\end{codebox}
-Gradle is based around the central concept of a build life cycle. The \rbox{compile} phase, as the name suggests, compiles the source code of the project using the underlying Java compiler. After compiling, the code can be packaged, tested and run. The \rbox{build} target actually compiles, tests and packages our tool. Afterwards, you will have a \abox[araracolour]{application/build/libs/} directory with multiple JAR files, one containing \rbox{with-deps}. That file is ready to run as it bundles all dependencies. Subsequent builds will be significantly faster than the first build because they do not fetch dependencies and rely on a build cache. Finally, after some time, Gradle will output the following message as result (please note that the entire compilation and packaging only took 4 seconds on my development machine due to an existing local cache):
+Gradle is based around the central concept of a build life cycle. The \rbox{compile} phase, as the name suggests, compiles the source code of the project using the underlying Java compiler. After compiling, the code can be packaged, tested and run. The \rbox{build} target actually compiles, tests and packages our tool. Afterwards, you will have a \abox[araracolour]{cli/build/libs/} directory with multiple JAR files, one containing \rbox{with-deps}. That file is ready to run as it bundles all dependencies. Subsequent builds will be significantly faster than the first build because they do not fetch dependencies and rely on a build cache. Finally, after some time, Gradle will output the following message as result (please note that the entire compilation and packaging only took 4 seconds on my development machine due to an existing local cache):
\begin{codebox}{Terminal}{teal}{\icnote}{white}
BUILD SUCCESSFUL in 4s
@@ -111,7 +112,7 @@ BUILD SUCCESSFUL in 4s
Now, let us move the resulting Java archive file from that particular directory to our current directory. Run the following command in the terminal (please note that the Java archive file was also renamed during the move operation):
\begin{codebox}{Terminal}{teal}{\icnote}{white}
-$ mv application/build/libs/arara-with-deps-*.jar arara.jar
+$ mv cli/build/libs/arara-cli-with-deps-*.jar arara.jar
\end{codebox}
Now, our current directory contains the final \rbox{arara.jar} Java archive file properly built from source. This file can be safely distributed and deployed, as seen later on, in Chapter~\ref{chap:deployingthetool}, on page~\pageref{chap:deployingthetool}. You can also test the resulting file by running the following command in the terminal:
@@ -123,23 +124,31 @@ $ java -jar arara.jar
| (_| | | | (_| | | | (_| |
\__,_|_| \__,_|_| \__,_|
-Usage: arara [OPTIONS] [file]...
+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
+ -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
+ -s, --safe-run Run in safe mode and disable
+ potentially harmful features. Make
+ sure your projects uses only allowed
+ features.
+ -H, --header Extract directives only in the file
+ header
+ -p, --preamble TEXT Set the file preamble based on the
+ configuration file
+ -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)
+ -d, --working-directory PATH Set the working directory for all
+ tools
+ -P, --call-property VALUE Pass parameters to the application
+ to be used within the session.
+ -V, --version Show the version and exit
+ -h, --help Show this message and exit
Arguments:
file The file(s) to evaluate and process