tex-framework/content.tex

\section{Bootloader}
To build a bootloader for the project \textit{moray white 2} you have to do the
following steps:\\
\begin{enumerate}
\item check/edit build job file
\item check/edit configuration file
\item create release tag in gitlab
\end{enumerate}

\subsection{Build job file}
The build job file (\texttt{.gitlab-ci.yml}) could be found in the root
directory of the repository. Here only the build configuration is done. In the
\texttt{variables} Section the variable \texttt{PROJECT} contains the current
build configuration.\\
Possible build configurations:

\captionof{table}{Values for build configutation}
\label{tab:var_build_confs}
\begin{tabular}{l l}
	\cellcolor{black}\color{white}build config & \cellcolor{black}\color{white}meaning \\
	white2-dbg & use the debug configuration to build the release\\
	white2-rel & use the release configuration to build the release\\\\
\end{tabular}

\textbf{Example}
\lstsetbash
\begin{lstlisting}
variables:
  PROJECT: "white2-dbg"
...
\end{lstlisting}
\begin{lstlisting}
variables:
  PROJECT: "white2-rel"
...
\end{lstlisting}

\subsection{Configuration file}
The configuration file (\texttt{configuration.xml}) depends on the build
configuration (\texttt{white2-dbg} or \texttt{white2-rel}) and could be found
in following folder (relative to the repositories root folder):\\
\begin{lstlisting}
moray/config/<build_config>/
\end{lstlisting}
Amongst others informations regarding version numbers, deploy file names and
deploy locations are encapsulated in the \texttt{postlink} target.

\captionof{table}{Release relevant attributes in configuration file}
\label{tab:conf_vars}
\begin{tabular}{l l}
	\cellcolor{black}\color{white}attributes & \cellcolor{black}\color{white}meaning \\
	OUT\_EXECUTABLE\_NAME & file name for the bootloader executable\\
	REL\_VERSION & version numbering scheme\\
	OUT\_DEPLOY\_PATH & subversion link to deploy the release to\\\\
\end{tabular}

It's usually enough to change \texttt{OUT\_EXECUTABLE\_NAME} and
\texttt{REL\_VERSION} according to the release numbering scheme.\\\\

\textbf{Example}
\begin{lstlisting}
...
    <attribute name="OUT_EXECUTABLE_NAME"
        value="MO_BL_42_3.0.6_dbg.S19"/>
    <attribute name="REL_VERSION"
        value="42.3.0.6"/>
    <attribute name="OUT_DEPLOY_PATH"
        value="http://dabsvn01.internal.novero.com/svn/\
        0_31X_P0521_moray_white2/trunk/development/\
        software/releases/WTC/"/>
...
\end{lstlisting}
\subsection{Create release tag in gitlab}
To create a release candidate a tag in gitlab has to be created. Of course this
could be done either locally (don't forget to push the tag) or by using the
gitlab ui.
\subsubsection{Release candidate}
To create a release candidate the tag name must match the following regular
expression:
\begin{lstlisting}
^release/white2/MO_BL_42_[0-9]+\.[0-9]+\.[0-9]+_RC[0-9]+
\end{lstlisting}

\textbf{Example}
\begin{lstlisting}
release/white2/MO_BL_42_0.0.0_RC0
release/white2/MO_BL_42_255.255.255_RC255
\end{lstlisting}

\subsubsection{Release}
To create a release the tag name must match the following regular expression:
\begin{lstlisting}
^release/white2/MO_BL_42_[0-9]+\.[0-9]+\.[0-9]+
\end{lstlisting}

\textbf{Example}
\begin{lstlisting}
release/white2/MO_BL_42_0.0.0
release/white2/MO_BL_42_255.255.255
\end{lstlisting}

\textbf{Note:} Any tag which shouldn't trigger a release build must not match
these regular expression rules.

\section{Application}
For application building in the project \textit{moray white 2} the same steps as
for bootloader building are necessary:\\
\begin{enumerate}
\item check/edit build job file
\item check/edit configuration file
\item create release tag in gitlab
\end{enumerate}

\subsection{Build job file}
The build job file (\texttt{.gitlab-ci.yml}) could be found in the root
directory of the repository. Here only the build configuration is done. In the
\texttt{variables} Section the variable \texttt{PROJECT} contains the current
build configuration.\\
Possible build configurations:

\captionof{table}{Values for build configutation}
\label{tab:var_build_confs}
\begin{tabular}{l l}
	\cellcolor{black}\color{white}build config & \cellcolor{black}\color{white}meaning \\
	white2-dbg & use the debug configuration to build the release\\
	white2-rel & use the release configuration to build the release\\\\
\end{tabular}

\textbf{Example}
\lstsetbash
\begin{lstlisting}
variables:
  PROJECT: "white2-dbg"
...
\end{lstlisting}
\begin{lstlisting}
variables:
  PROJECT: "white2-rel"
...
\end{lstlisting}

\subsection{Configuration file}
The configuration file (\texttt{configuration.xml}) depends on the build
configuration (\texttt{white2-dbg} or \texttt{white2-rel}) and could be found
in following folder (relative to the repositories root folder):\\
\begin{lstlisting}
config/<build_config>/
\end{lstlisting}
Amongst others informations regarding version numbers, bootloader location,
deploy file names and deploy locations are encapsulated in the \texttt{postlink}
target.

\captionof{table}{Release relevant attributes in configuration file}
\label{tab:conf_vars}
\begin{tabular}{l l}
	\cellcolor{black}\color{white}attributes & \cellcolor{black}\color{white}meaning \\
	OUT\_EXECUTABLE\_NAME & file name for the bootloader executable\\
	REL\_VERSION & version numbering scheme\\
	IN\_BOOTLOADER\_URL & path to the bootloader url containing the\\
	& regarding bootloader executable\\
	OUT\_DEPLOY\_PATH & subversion link to deploy the release to\\\\
\end{tabular}

It's usually enough to change \texttt{OUT\_EXECUTABLE\_NAME} and
\texttt{REL\_VERSION} according to the release numbering scheme. Only in case of
a changed bootloader the \texttt{IN\_BOOTLOADER\_URL} has to be changed.\\\\

\textbf{Example}
\begin{lstlisting}
...
    <attribute name="OUT_EXECUTABLE_NAME"
        value="MO_BL_42_3.0.6_dbg.S19"/>
    <attribute name="REL_VERSION"
        value="42.3.0.6"/>
    <attribute name="IN_BOOTLOADER_URL" value="http://\
        dabsvn01/svn/0_31X_P0521_moray_white2/trunk/\
        development/software/releases/WTC/Bootloader/\
        MO_BL_42_3.1.6.S19"/>
    <attribute name="OUT_DEPLOY_PATH"
        value="http://dabsvn01.internal.novero.com/svn/\
        0_31X_P0521_moray_white2/trunk/development/\
        software/releases/WTC/"/>
...
\end{lstlisting}
\subsection{Create release tag in gitlab}
To create a release candidate a tag in gitlab has to be created. Of course this
could be done either locally (don't forget to push the tag) or by using the
gitlab ui.
\subsubsection{Release candidate}
To create a release candidate the tag name must match the following regular
expression:
\begin{lstlisting}
^release/white2/MO_WC_42_[0-9]+\.[0-9]+\.[0-9]+_RC[0-9]+
\end{lstlisting}

\textbf{Example}
\begin{lstlisting}
release/white2/MO_WC_42_0.0.0_RC0
release/white2/MO_WC_42_255.255.255_RC255
\end{lstlisting}

\subsubsection{Release}
To create a release the tag name must match the following regular expression:
\begin{lstlisting}
^release/white2/MO_WC_42_[0-9]+\.[0-9]+\.[0-9]+
\end{lstlisting}

\textbf{Example}
\begin{lstlisting}
release/white2/MO_WC_42_0.0.0
release/white2/MO_WC_42_255.255.255
\end{lstlisting}

\textbf{Note:} Any tag which shouldn't trigger a release build must not match
these regular expression rules.