wip

Makefile

@@ -4,8 +4,6 @@ DEP := \
 	config/headfoot.tex	\
 	config/sourcelst.tex	\
 	content.tex		\
-	gitlab-runner.tex	\
-	title.tex		\
 	Makefile
 
 all: $(MAIN)

content.tex

@@ -1,66 +1,216 @@
-\section{Introduction}
+\section{Bootloader}
-Gitlab-ci uses so called runners to execute the build jobs defined in the build
+To build a bootloader for the project \textit{moray white 2} you have to do the
-job file of a repository. A runner is a seperate tool and can be installed on
+following steps:\\
-any machine. The type of connection is configurable. The intentions of these concept are:\\
+\begin{enumerate}
-\begin{itemize}
+\item check/edit build job file
-	\item{remove (build) environmental dependency from ci server}
+\item check/edit configuration file
-	\item{multipe runners to parallize multiple builds}
+\item create release tag in gitlab
-\end{itemize}
+\end{enumerate}
-The Runner has to be installed on a machine with a proper environment (compiler,
-...) installed for the dedicated project it is used for. Figure \ref{fig:gitlab-runner-interaction} illustrates
-the interaction of a local workstation, the gitlab(-ci) server and the
-gitlab-ci-multi-runner.
-\begin{figure}
-	\begin{center}
-		\input{gitlab-runner.tex}
-		\caption{Gitlab-ci - runner interaction}
-		\label{fig:gitlab-runner-interaction}
-	\end{center}
-\end{figure}
 
-\section{Installation of gitlab-ci-multi-runner}
+\subsection{Build job file}
-The Installation of the runner depends on the operating system of the host and
+The build job file (\texttt{.gitlab-ci.yml}) could be found in the root
-is described here: \hyperlink{https://docs.gitlab.com/runner/install/}{\texttt{https://docs.gitlab.com/runner/install}}
+directory of the repository. Here only the build configuration is done. In the
-\section{Installation of a dedicated runner}
+\texttt{variables} Section the variable \texttt{PROJECT} contains the current
-\subsection{Prerequisites}
+build configuration.\\
-To install a dedicated runner prerequisites has to be fullfilled:
+Possible build configurations:
-\begin{itemize}
+
-	\item{Url of gitlab ci coordinator}
+\captionof{table}{Values for build configutation}
-	\item{Registation token of that server}
+\label{tab:var_build_confs}
-	\item{Tags - if the build job defines tags to identify runners}
+\begin{tabular}{l l}
-\end{itemize}
+	\cellcolor{black}\color{white}build config & \cellcolor{black}\color{white}meaning \\
-These two informations can be gathered at the runners section of the project's
+	white2-dbg & use the debug configuration to build the release\\
-gitlab repository the runner is installed for. That section is accessible using:\texttt{<gitlab-url>/<project-path>/runners}\\
+	white2-rel & use the release configuration to build the release\\\\
-\textbf{Example:}\\
+\end{tabular}
-\texttt{https://novgit05.novero.com/agricola/agricola/runners}
+
-\subsection{Register}
+\textbf{Example}
-Open a shell an type: \texttt{gitlab-ci-multi-runner register}. An interactive
+\lstsetbash
-shell opens and requests some inputs (see prequisites).
-\lstsetdefault
 \begin{lstlisting}
-user@dabbld01:~$ sudo gitlab-ci-multi-runner register
+variables:
-Running in system-mode.
+  PROJECT: "white2-dbg"
-
+...
-Please enter the gitlab-ci coordinator URL
+\end{lstlisting}
-(e.g. https://gitlab.com/):
+\begin{lstlisting}
-https://novgit05.novero.com/ci
+variables:
-Please enter the gitlab-ci token for this runner:
+  PROJECT: "white2-rel"
-<secret-token>
+...
-Please enter the gitlab-ci description for this runner:
-[dabbld01]:
-my-runner
-Please enter the gitlab-ci tags for this runner (comma
-separated):
-
-Please enter the executor: shell, docker+machine,
-docker-ssh+machine, kubernetes, docker, docker-ssh,
-parallels, ssh, virtualbox:
-shell
-Runner registered successfully. Feel free to start it,
-but if it's running already the config should be
-automatically reloaded!
 \end{lstlisting}
 
-\subsection{Start as service}
+\subsection{Configuration file}
-Open a shell an type: \texttt{gitlab-ci-multi-runner start}
+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.
 

gitlab-runner.tex

@@ -1,23 +0,0 @@
-\psset{griddots=0,gridlabels=8pt,subgriddiv=5}
-\psset{xunit=10mm,yunit=10mm}
-\newcommand{\clr}{black}
-\psset{fillcolor=white}
-\psset{fillstyle=solid}
-\psset{linecolor=\clr}
-\psset{framearc=.5}
-\psset{framesep=20pt}
-\psset{arrowsize=10pt}
-\begin{pspicture}(12,6)
-%	\psgrid
-	\rput(2.5,5){\psframebox{\textcolor{\clr}{Gitlab-ci server}}}
-	\rput(2.5,1){\psframebox{\textcolor{\clr}{Local workstation}}}
-	\rput(8.5,3){\psframebox{\textcolor{\clr}{Gitlab-ci-multi-runner}}}
-	\pscurve[fillstyle=none]{->}(4.6,5)(7.2,5)(8.5,3.9)
-	\pscurve[fillstyle=none]{<-}(3,4.1)(4,3.2)(5.8,3)
-	\pscurve[fillstyle=none]{<-}(8,2.1)(7.7,1.4)(8.5,.8)(9.3,1.4)(9,2.1)
-	\psline{->}(1,1.9)(1,4.1)
-	\rput(7,5.3){build trigger}
-	\rput(.5,3){push}
-	\rput(4,2.6){build result}
-	\rput(8.5,.5){build}
-\end{pspicture}

title.tex

@@ -1,4 +1,4 @@
-\newcommand{\docname}{Gitlab-ci}
+\newcommand{\docname}{Create release}
-\newcommand{\prjname}{gitlab-ci-multi-runner}
+\newcommand{\prjname}{moray white2}
 \newcommand{\docversion}{0.1}
 \newcommand{\docauthor}{Thomas Klaehn}