<commit_before>\documentclass[a4paper,12pt,english,oneside,halfparskip]{scrartcl}
\usepackage[utf8]{inputenc}
\usepackage{babel}
\usepackage{xspace}
\usepackage{amssymb}
\usepackage{ifpdf}
\usepackage{listings}
\usepackage{mdwlist}
\usepackage[svgnames]{xcolor}
\usepackage{hyperref}

\usepackage[T1]{fontenc}
\usepackage{lmodern}
\renewcommand*\familydefault{\sfdefault} %% Only if the base font of the document is to be sans serif

% \newcommand{\CMVN}{\fontseries{sbc}\selectfont{}\texttt{cmvn}\fontseries{sf}\selectfont}
\newcommand{\CMVN}{\texttt{cmvn}}
\newcommand{\cmvn}{\texttt{cmvn}}
\newcommand{\VERSION}{0.1.0}

\definecolor{listgray}{rgb}{0.88,0.88,0.88} 

\newcommand{\G}{\par\noindent\ensuremath{\blacktriangleright}~}
\newcommand{\GG}{\par\vspace{-\parskip}\hspace{1.4em}\ensuremath{\triangleright}~}
\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\pom}{\code{pom.xml}}

% \newenvironment{notes}{\begin{blockquote}}{\end{blockquote}}

%opening
\title{cmvn - Configured~Maven User~Manual}
\author{<NAME>}
\date{Version \VERSION}

\makeatletter
\hypersetup{
	pdfauthor={\@author}
	,pdftitle={\@title}
	%,pdfsubject={\@subjectpdf}
	%,pdfkeywords={\@keywords}
% 	,linktocpage
	,colorlinks=true
		, linkcolor=DarkBlue, citecolor=Red, urlcolor=MediumBlue
	,bookmarksnumbered
}
\makeatother


%%% JavaCode-Listings
%%% Optional: weitere lst-Optionen, wie z.B. caption und label
\lstnewenvironment{JavaCode}[1][]{%
	\lstset{
		language=Java
		,basicstyle=\footnotesize
		,tabsize=2
		,captionpos=t
% 		,numbers=left
% 		,numberblanklines=true, numberstyle=\scriptsize, stepnumber=2
		,aboveskip={\bigskipamount}, belowskip={\medskipamount}
% 		,abovecaptionskip={\medskipamount}
 		,belowcaptionskip={\medskipamount}
		,breaklines, breakatwhitespace
		, #1
	}
}{}

%%% JavaCode-Listings
%%% Optional: weitere lst-Optionen, wie z.B. caption und label
\lstnewenvironment{Cmdline}[1][]{%
	\lstset{language=sh
		,basicstyle=\ttfamily\footnotesize
		,tabsize=2
		,captionpos=t
% 		,numbers=left
% 		,numberblanklines=true, numberstyle=\scriptsize, stepnumber=2
		,aboveskip={\bigskipamount}, belowskip={\medskipamount}
% 		,abovecaptionskip={\medskipamount}
 		,belowcaptionskip={\medskipamount}
		,breaklines, breakatwhitespace
		,backgroundcolor=\color{listgray} 
		,frame=tbrl %t: top, r, b, l 
% 		,frameround=tttt
		, #1
	}
}{}

\sloppy

\begin{document}
\renewcommand{\labelitemi}{$\triangleright$}

\maketitle

% \begin{abstract}
% This Handbook describes \CMVN{} in version \VERSION{}.
% 
% \end{abstract}

\clearpage

\ifpdf\pdfbookmark[1]{Contents}{bm:Contents}\fi
\tableofcontents

\clearpage

\section{Introduction}

\CMVN{} is a helper tool for developers targeted at the Java Virtual Machine (JVM). Its main focus is to declaratively describe and configure the required development and build environment. 

A most significant difference between Java-targeted build systems compared to those for C/C++\footnote{e.g. Autotools + GNU Make, CMake, Scons.} is the lack of a defined configuration step before executing the compiler. Although building a Java application is a lot more easy compared to platform dependent programming languages and tools, nevertheless a lot of the (configuration) tasks of those other build systems are still required. Often the lack of a configuration process in Java build systems results in very obscure setups.

A very popular build system for Java is Apache Maven\footnote{\url{http://maven.apache.org}}, currently in version 3. It partially helps the developer with managing her dependencies but fails miserably at producing reliable builds, at least without support of a complex build infrastructure.\footnote{...like a Repository Manager.}

\CMVN{} tries to close this gap by providing a configuration step before the actual build system. Concrete, this goal will be reached by generating the build scripts for the underlying (nativ) build system. Whenever a configuration has changed \cmvn{} will first regenerate the build scripts and after that executes the underlying build system with the right (configured) settings. To assist the developer but do not stay in his way, \CMVN{} does not aim to replace existing build chains. Instead, its main focus is adding another (first) configuration step to the build chain to create more reliable and reproducable build environments.

In its first release \CMVN{} supports Apache Maven 2.0 and above\footnote{Using Apache Maven 3.0 is highly recommended.}. In later releases support for various other build chains will be added, e.g. Apache Ant + Ivy, SBT, JackBuild, or others. Although \CMVN{} generates the build scripts (in Maven case: \pom{} files) is does not can and it wants not handle all aspects of the underlying build infrastructure. To leave the full power to the developer, \CMVN{} supports templates for the underlying build scripts for those settings \CMVN{} can not generate. But for common project setup, this is rarely needed.

\section{Execution Modes}

\CMVN{} can be run in different execution modes:

\begin{itemize}
 \item Configuration
 \item Build
 \item Cleanup
\end{itemize}

The execution mode is given as (first) parameter when executing \CMVN{}.



\subsection{Configuration}

Simplest Example: 

\begin{Cmdline}
shell> cmvn --configure
\end{Cmdline}

Just generate the needed build scripts (if needed) of the underlying buildsystem.

For Maven this generates a \pom{} and a Maven settings file \code{.cmvn/settings.xml} in a local hidden directory.

\subsubsection{Automatic re-configuration}

To reconfigure an already configured project, e.g. because the \cmvn{} config file has changed or a generated file is missing, one can use the option \code{--reconfigure} which does exactly the same as \code{--configure} except that the concrete initial configuration is preserved, thus only the files were recreated without changing the current configuration. 

\begin{Cmdline}
shell> cmvn --reconfigure
\end{Cmdline}

If \cmvn{} detects, that the current project is not up-to-date, it must be used with \code{--reconfigure}. To avoid the burden of beeing forced to run a \code{cmvn --reconfigure} after each change of the project (or sub project) configuration, the option \code{--auto-reconfigure} can be used together with \code{--configure}. 

\begin{Cmdline}
shell> cmvn --configure --auto-reconfigure
\end{Cmdline}

Configured that way, \cmvn{} will automatically reconfigure the project (and the whole project tree) before a build, if needed.

\subsubsection{Maven Settings}

By default, \code{cmvn --configure} initally created an new project-local Maven settings file and thus uses a project-local repository. This is intended to isolate projects from each other while still maintaining project-interoperability via (remotely) realeased dependencies. This default way enables the developer to easy build branches without fearing of interferences and inconsistencies caused by multiple projects (branches) that are releasing to the same local repository. 

Of course, the newly created repository and Maven settings file is shared between all sub projects of the one you just configured.

In case, this default behavior is not desired, you can tell \cmvn{} to use an alternative existing Maven settings file with the option \code{--maven-settings}. In this case, you may will loose the benefits of side-effect free development of multiple project on the same computer. Also this may limit the reproducability of the build process in different environments. 

\begin{Cmdline}
shell> cmvn --configure --maven-settings=/home/user/.m2/settings.xml
\end{Cmdline}


Notice, that if you use an alternative Maven settings file, \cmvn{} will not touch this file and the Local Maven Repository when running in cleanup execution mode.

\subsection{Build}

Maven Example: Clean project build and install the build jar file into the local Maven repository.

\begin{Cmdline}
shell> cmvn --build clean install
\end{Cmdline}

The build execution mode is automatically enabled if no other mode was requested and at least one non-option argument was given to \CMVN{}. So the example above could also be written as:

\begin{Cmdline}
shell> cmvn clean install
\end{Cmdline}

If \cmvn{} is run without any option and parameter but the project was configured with the \code{reconfigure}-option, all necessary project files will be regenerated automatically if needed.\footnote{Without the \code{auto-reconfigure} setting the same behavior can be achieved by running \code{cmvn --reconfigure}.}



\subsection{Cleanup}

The execution mode cleanup is used to remove all generated files and the configuration data. Currently there are two variants to enable the cleanup mode: one version enabled with \code{--clean} removes only the generated native build scripts, the other variant \code{--distclean} cleans also the configuration state and any other generated environment setup, e.g. a hidden project local Maven repository.

\begin{Cmdline}
shell> cmvn --clean
\end{Cmdline}

Cleans up all generated native build scripts.

\begin{Cmdline}
shell> cmvn --distclean<commit_msg>Fixed typo and added info about template file.<commit_after>\documentclass[a4paper,12pt,english,oneside,halfparskip]{scrartcl}
\usepackage[utf8]{inputenc}
\usepackage{babel}
\usepackage{xspace}
\usepackage{amssymb}
\usepackage{ifpdf}
\usepackage{listings}
\usepackage{mdwlist}
\usepackage[svgnames]{xcolor}
\usepackage{hyperref}

\usepackage[T1]{fontenc}
\usepackage{lmodern}
\renewcommand*\familydefault{\sfdefault} %% Only if the base font of the document is to be sans serif

% \newcommand{\CMVN}{\fontseries{sbc}\selectfont{}\texttt{cmvn}\fontseries{sf}\selectfont}
\newcommand{\CMVN}{\texttt{cmvn}}
\newcommand{\cmvn}{\texttt{cmvn}}
\newcommand{\VERSION}{0.1.0}

\definecolor{listgray}{rgb}{0.88,0.88,0.88} 

\newcommand{\G}{\par\noindent\ensuremath{\blacktriangleright}~}
\newcommand{\GG}{\par\vspace{-\parskip}\hspace{1.4em}\ensuremath{\triangleright}~}
\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\pom}{\code{pom.xml}}

% \newenvironment{notes}{\begin{blockquote}}{\end{blockquote}}

%opening
\title{cmvn - Configured~Maven User~Manual}
\author{<NAME>}
\date{Version \VERSION}

\makeatletter
\hypersetup{
	pdfauthor={\@author}
	,pdftitle={\@title}
	%,pdfsubject={\@subjectpdf}
	%,pdfkeywords={\@keywords}
% 	,linktocpage
	,colorlinks=true
		, linkcolor=DarkBlue, citecolor=Red, urlcolor=MediumBlue
	,bookmarksnumbered
}
\makeatother


%%% JavaCode-Listings
%%% Optional: weitere lst-Optionen, wie z.B. caption und label
\lstnewenvironment{JavaCode}[1][]{%
	\lstset{
		language=Java
		,basicstyle=\footnotesize
		,tabsize=2
		,captionpos=t
% 		,numbers=left
% 		,numberblanklines=true, numberstyle=\scriptsize, stepnumber=2
		,aboveskip={\bigskipamount}, belowskip={\medskipamount}
% 		,abovecaptionskip={\medskipamount}
 		,belowcaptionskip={\medskipamount}
		,breaklines, breakatwhitespace
		, #1
	}
}{}

%%% JavaCode-Listings
%%% Optional: weitere lst-Optionen, wie z.B. caption und label
\lstnewenvironment{Cmdline}[1][]{%
	\lstset{language=sh
		,basicstyle=\ttfamily\footnotesize
		,tabsize=2
		,captionpos=t
% 		,numbers=left
% 		,numberblanklines=true, numberstyle=\scriptsize, stepnumber=2
		,aboveskip={\bigskipamount}, belowskip={\medskipamount}
% 		,abovecaptionskip={\medskipamount}
 		,belowcaptionskip={\medskipamount}
		,breaklines, breakatwhitespace
		,backgroundcolor=\color{listgray} 
		,frame=tbrl %t: top, r, b, l 
% 		,frameround=tttt
		, #1
	}
}{}

\sloppy

\begin{document}
\renewcommand{\labelitemi}{$\triangleright$}

\maketitle

% \begin{abstract}
% This Handbook describes \CMVN{} in version \VERSION{}.
% 
% \end{abstract}

\clearpage

\ifpdf\pdfbookmark[1]{Contents}{bm:Contents}\fi
\tableofcontents

\clearpage

\section{Introduction}

\CMVN{} is a helper tool for developers targeted at the Java Virtual Machine (JVM). Its main focus is to declaratively describe and configure the required development and build environment. 

A most significant difference between Java-targeted build systems compared to those for C/C++\footnote{e.g. Autotools + GNU Make, CMake, Scons.} is the lack of a defined configuration step before executing the compiler. Although building a Java application is a lot more easy compared to platform dependent programming languages and tools, nevertheless a lot of the (configuration) tasks of those other build systems are still required. Often the lack of a configuration process in Java build systems results in very obscure setups.

A very popular build system for Java is Apache Maven\footnote{\url{http://maven.apache.org}}, currently in version 3. It partially helps the developer with managing her dependencies but fails miserably at producing reliable builds, at least without support of a complex build infrastructure.\footnote{...like a Repository Manager.}

\CMVN{} tries to close this gap by providing a configuration step before the actual build system. Concrete, this goal will be reached by generating the build scripts for the underlying (nativ) build system. Whenever a configuration has changed \cmvn{} will first regenerate the build scripts and after that executes the underlying build system with the right (configured) settings. To assist the developer but do not stay in his way, \CMVN{} does not aim to replace existing build chains. Instead, its main focus is adding another (first) configuration step to the build chain to create more reliable and reproducable build environments.

In its first release \CMVN{} supports Apache Maven 2.0 and above\footnote{Using Apache Maven 3.0 is highly recommended.}. In later releases support for various other build chains will be added, e.g. Apache Ant + Ivy, SBT, JackBuild, or others. Although \CMVN{} generates the build scripts (in Maven case: \pom{} files) is does not can and it wants not handle all aspects of the underlying build infrastructure. To leave the full power to the developer, \CMVN{} supports templates for the underlying build scripts for those settings \CMVN{} can not generate. But for common project setup, this is rarely needed.

\section{Execution Modes}

\CMVN{} can be run in different execution modes:

\begin{itemize}
 \item Configuration
 \item Build
 \item Cleanup
\end{itemize}

The execution mode is given as (first) parameter when executing \CMVN{}.



\subsection{Configuration}

Simplest Example: 

\begin{Cmdline}
shell> cmvn --configure
\end{Cmdline}

Just generate the needed build scripts (if needed) of the underlying buildsystem.

For Maven this generates a \pom{} and a Maven settings file \code{.cmvn/settings.xml} in a local hidden directory.

\subsubsection{Automatic re-configuration}

To reconfigure an already configured project, e.g. because the \cmvn{} config file has changed or a generated file is missing, one can use the option \code{--reconfigure} which does exactly the same as \code{--configure} except that the concrete initial configuration is preserved, thus only the files were recreated without changing the current configuration. 

\begin{Cmdline}
shell> cmvn --reconfigure
\end{Cmdline}

If \cmvn{} detects, that the current project is not up-to-date, it must be used with \code{--reconfigure}. To avoid the burden of beeing forced to run a \code{cmvn --reconfigure} after each change of the project (or sub project) configuration, the option \code{--auto-reconfigure} can be used together with \code{--configure}. 

\begin{Cmdline}
shell> cmvn --configure --auto-reconfigure
\end{Cmdline}

Configured that way, \cmvn{} will automatically reconfigure the project (and the whole project tree) before a build, if needed.

\subsubsection{Maven Settings}

By default, \code{cmvn --configure} initally created an new project-local Maven settings file and thus uses a project-local repository. This is intended to isolate projects from each other while still maintaining project-interoperability via (remotely) realeased dependencies. This default way enables the developer to easy build branches without fearing of interferences and inconsistencies caused by multiple projects (branches) that are releasing to the same local repository. 

Of course, the newly created repository and Maven settings file is shared between all sub projects of the one you just configured.

In case, this default behavior is not desired, you can tell \cmvn{} to use an alternative existing Maven settings file with the option \code{--maven-settings}. In this case, you may will loose the benefits of side-effect free development of multiple project on the same computer. Also this may limit the reproducability of the build process in different environments. 

\begin{Cmdline}
shell> cmvn --configure --maven-settings /home/user/.m2/settings.xml
\end{Cmdline}

Notice, that if you use an alternative Maven settings file, \cmvn{} will not touch this file and the Local Maven Repository when running in cleanup execution mode.


\subsubsection{Using Templates -- \code{pom.xml.cmvn}}

When \cmvn{} detects the presence of a file \code{pom.xml.cmvn} it will use it as template when generating the \pom{} file for Maven. \cmvn{} will first read the template file and afterward extend it with the settings found in \code{cmvn.conf}. You can use this to easily migrate existing Maven projects or if you need complex setups and Maven features (like \code{<profile>}). 


\subsection{Build}

Maven Example: Clean project build and install the build jar file into the local Maven repository.

\begin{Cmdline}
shell> cmvn --build clean install
\end{Cmdline}

The build execution mode is automatically enabled if no other mode was requested and at least one non-option argument was given to \CMVN{}. So the example above could also be written as:

\begin{Cmdline}
shell> cmvn clean install
\end{Cmdline}

If \cmvn{} is run without any option and parameter but the project was configured with the \code{reconfigure}-option, all necessary project files will be regenerated automatically if needed.\footnote{Without the \code{auto-reconfigure} setting the same behavior can be achieved by running \code{cmvn --reconfigure}.}



\subsection{Cleanup}

The execution mode cleanup is used to remove all generated files and the configuration data. Currently there are two variants to enable the cleanup mode: one version enabled with \code{--clean} removes only the generated native build scripts, the other variant \code{--distclean} cleans also the configuration state and any other generated environment setup, e.g. a hidden project local Maven repository.

\begin{Cmdline}
shell> cmvn --clean
\end{Cmdline}

Cleans up all generated native build scripts.

\begin{Cmdline}
shell> cmvn --distclean
{'fraction_non_alphanumeric': 0.09199227136109918, 'fraction_numerical': 0.0038643194504079004, 'mean_word_length': 5.002899484536083, 'pattern_counts': {'":': 0, '<': 6, '<?xml version=': 0, '>': 22, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 8}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7580892', 'n_tokens_mistral': 5415, 'n_tokens_neox': 5114, 'n_words': 2134}