@@ -12,7 +12,8 @@ run ./debian_install.sh under root, asnwer simple questions.
It will install all the needed packages.
-Install toolchains for needed platforms to /home/jenkins/tools and add them to tools.sh file.
+Install toolchains for needed platforms into /home/jenkins/tools
+and add them to tools.sh file.
See jta-guide.pdf for details.
@@ -1,28 +1,35 @@
\section{Boards configuration}
In this document we will use such notions as \textit{targets} and \textit{boards}. Here is what they mean:
\begin{description}
-\item[Target or Node] is denoted as a front-end Jenkins entity. Jenkins jobs are run on targets.
-\item[Board] is denoted as a back-end entity. Board is defined by it's \texttt{.board} file with necessary variable definitions for running tests.
+\item [Target or Node] denotes a front-end Jenkins entity. Jenkins jobs are run on targets.
+\item [Board] denotes a back-end entity, such as a physical board (specifically, the board or device to run tests on).
+A board is defined by it's \texttt{.board} file with
+the variable definitions that are necessary for running tests on that board.
\end{description}
-Board configuration is done in \texttt{JTA\_ENGINE\_PATH/overlays/boards/<boardname>.board}, where \texttt{<boardname>} is the respective name of the target.
+The board configuration is stored in a file named \texttt{JTA\_ENGINE\_PATH/overlays/boards/<boardname>.board},
+where \texttt{<boardname>} is the respective name of the physical board under test.
-\subsection{Adding a target in frontend}
+\subsection{Adding a target in the Jenkins interface}
\label{sec:target-add}
-The simplest method is to copy from existing one. We provide \textit{template-dev} board for that purpose.
+The simplest method of adding a new target is to copy from an existing one.
+We provide a board named \textit{template-dev} for that purpose.
\begin{enumerate}
-\item Click \href{http://localhost:8080/computer/}{Target status}
-\item Click \href{http://localhost:8080/computer/new}{New node}
-\item Fill in the \textit{Node name} input field.
-\item Choose \textit{Copy Existing Node}. And enter name of source node, namely, \textit{Generic}
-\item You will be forwarded to node configuration page. Locate \textit{Environment variables} section in \textit{Node Properties}. Specify path to board config file [\ref{sec:board_config}] using the variable \textbf{BOARD\_OVERLAY}.
+\item Open a browser window to the \href{http://localhost:8080/}{JTA web interface}
+\item Click on \textbf{Target status}
+\item Click on \textbf{New node}
+\item Fill in the \textit{Node name} input field witht he name of the new board
+\item Choose \textit{Copy Existing Node}. And enter name of the source node, namely, \textit{template-dev}
+\item You will be forwarded to node configuration page.
+Locate the \textit{Environment variables} section in \textit{Node Properties}.
+Specify the path to board config file [\ref{sec:board_config}] using the variable \textbf{BOARD\_OVERLAY}.
\end{enumerate}
-\subsection{Writing board config overlay}
+\subsection{Writing the board config overlay}
\label{sec:board_config}
-Board config file is an overlay (See \ref{subsec:overlay_fmt}) that must inherit \texttt{base-board} and include \texttt{base-params} base classes (in that order).
+The board config file is an overlay (See \ref{subsec:overlay_fmt}) that must inherit \texttt{base-board} and include \texttt{base-params} base classes (in that order).
-The following is the step-by-step description of all mandatory environment variables should be set:
+The following is the step-by-step description of all mandatory environment variables that should be set by this file:
\begin{description}
\item[\texttt{TRANSPORT}:] defines how JTA should communicate with the board.
@@ -38,9 +45,6 @@ The following is the step-by-step description of all mandatory environment varia
The following variables specify devices and mount points that are used by some
file system tests: \texttt{SATA\_DEV, SATA\_MP, USB\_DEV, USB\_MP, MMC\_DEV, MMC\_MP}.
-
-
-
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "jta-guide"
@@ -3,31 +3,47 @@
\subsection{Prerequisites}
\label{sec:prereq}
+You need the following items in order to install and use JTA:
\begin{itemize}
-\item Debian \textbf{Wheezy}\footnote{Other Debian releases (Jessie, Sid) should work as well as other distributives, though they are not as thoroughly tested} for \textbf{AMD64} architecture. \\ It can be fetched from
+\item Debian \textbf{Wheezy}\footnote{Other Debian releases (Jessie, Sid) should work as well as other distributions, though they are not as thoroughly tested} distribution of Linux, for \textbf{AMD64} architecture. \\ It can be fetched from
\href{``http://cdimage.debian.org/cdimage/jessie_di_alpha_1/amd64/iso-cd/debian-jessie-DI-a1-amd64-netinst.iso''}{here};
-\item Web browser with \textbf{javascript} and \textbf{CSS} support.
+\item A web browser with \textbf{javascript} and \textbf{CSS} support.
\end{itemize}
\subsection{Running install script}
\label{sec:inst-steps}
\begin{itemize}
-\item Get JTA release via git:
+\item Get the JTA release via git:
\\
\texttt{git clone https://cogentembedded@bitbucket.org/cogentembedded/jta-public.git}
-\item Run install script under root: \texttt{./debian\_install.sh}\footnote{During the proecess script will call dpkg-reconfigure dash, asking a question about using dash. You must answer ``no'' to the dialogue.}
+\item Run the install script as root: \texttt{./debian\_install.sh}
+ \begin{itemize}
+ \item During the install you will be asked if you wish to continue using 'dash' instead of 'bash'
+as the default shell for your system. Please answer ``no'' to the dialogue that appears.
+Note that this may result in changing the default shell for your Linux system.
+ \end{itemize}
\end{itemize}
-
-When script finishes, JTA web interface will be available on local machine at port \href{http://localhost:8080}{8080}.
+When the script finishes, the JTA web interface should be available on your local machine at port 8080.
+That is, point your browser at \href{http://localhost:8080}{http://localhost:8080} to see the web
+interface for JTA.
+
+Note that the install script uses JTA\_ENGINE\_PATH to determine where to put material for the
+Jenkins engine. This defaults to /home/jenkins. In the remainder of this document you
+will see references to directories and files relative to this location.
\subsection{Installing toolchains and sysroots}
-You need toolchains and sysroots to build tests for different platforms.
+You will need toolchains and sysroots to build tests for different platforms.
\label{sec:toolchain-install}
\subsubsection{Using meta-jta OE layer for generating toolchain}
-We ship toolchains for koelsch and minnow boards that we build from poky from our \href{https://bitbucket.org/cogentembedded/meta-jta/}{custom layer}. If you already use OpenEmbedded from building rootfs for your system yoy can use our layer to generate toolchain and sysroot (using \texttt{bitbake meta-toolchain}) with all libraries and headers needed from building tests. See Poky \href{http://www.yoctoproject.org/docs/1.6/adt-manual/adt-manual.html}{Documentation} for more information.
+We ship toolchains for koelsch and minnow boards that we build using poky and our
+\href{https://bitbucket.org/cogentembedded/meta-jta/}{custom layer} for OpenEmbedded.
+If you already use OpenEmbedded for building the rootfs for your system you can use our
+layer to generate a toolchain and sysroot (using \texttt{bitbake meta-toolchain}) with
+all the libraries and headers needed for building tests.
+See Poky \href{http://www.yoctoproject.org/docs/1.6/adt-manual/adt-manual.html}{Documentation} for more information.
% \subsubsection{Using custom toolchain}
@@ -43,28 +59,38 @@ We ship toolchains for koelsch and minnow boards that we build from poky from ou
% \item \href{https://sourcery.mentor.com/GNUToolchain/subscription3130?lite=MIPS}{Mentor Graphics MIPS toolchain}
% \end{itemize}
-Toolchains and sysroots are usually stored in \texttt{JTA\_ENGINE\_PATH/tools} folder.
+Toolchains and sysroots are usually stored in the folder \texttt{JTA\_ENGINE\_PATH/tools}.
-\subsection{Configuring tools.sh file}
-\texttt{JTA\_ENGINE\_PATH/scripts/tools.sh} file is used to setup paths and compile flags for each platform.
+\subsection{Configuring the tools.sh file}
+The file \texttt{JTA\_ENGINE\_PATH/scripts/tools.sh} is used to setup paths and compile flags for each platform.
-For poky-generated toolchains one should source envirnoment file and set the following variables:
+For poky-generated toolchains one should set the following variables, and source this environment files:
\begin{itemize}
\item \texttt{SDKROOT} - path to rootfs
-\item \texttt{PREFIX} - gcc prefix, like \texttt{arm-blabla-linux-gnueabi}
-\item \texttt{HOST} - like \texttt{PREFIX}
+\item \texttt{PREFIX} - this is the gcc prefix, like \texttt{arm-blabla-linux-gnueabi}
+\item \texttt{HOST} - this is also the gcc prefix. It should be the same as \texttt{PREFIX}
\end{itemize}
-Also not code saving original \texttt{\$PATH} to \texttt{\$ORIG\_PATH} since envirnoment script changes it.
+Also note the code in the tools.sh file which saves the original \texttt{\$PATH} to \texttt{\$ORIG\_PATH}
+since environment script changes it.
-See [L. \ref{intel-minnow-tools}] for example.
+For an example of how to use configure the tools.sh file for a specific board, see
+listing [L. \ref{intel-minnow-tools}], which shows the variables used for
+the Intel minnowboard. You can copy these lines in tools.sh and edit the variables
+to match those for your board's toolchains.
\subsubsection{Using custom toolchain}
\label {subsec:custom-toolchain-tools-sh}
-For using custom toolchain you \emph{additionally} must define the following variables: \texttt{PATH, PKG\_CONFIG\_SYSROOT\_DIR, PKG\_CONFIG\_PATH, CC, CXX, CPP, AS, LD, RANLIB, AR, NM, CFLAGS, CXXFLAGS, LDFLAGS, CPPFLAGS, ARCH, CROSS\_COMPILE}.
+To use a custom toolchain you \emph{additionally} must define the following variables:
+\texttt{PATH, PKG\_CONFIG\_SYSROOT\_DIR, PKG\_CONFIG\_PATH, CC, CXX, CPP, AS, LD, RANLIB, AR, NM, CFLAGS, CXXFLAGS, LDFLAGS, CPPFLAGS, ARCH, CROSS\_COMPILE}.
+
+These are placed in an "environment\_setup..." file, located in the root directory of the
+tools folder under \texttt{JTA\_ENGINE\_PATH/tools} where the toolchain and sysroot for your board are installed.
-You can use \texttt{environment-setup-core2-32-osv-linux} script as reference.
+You can use the file \\
+\texttt{JTA\_ENGINE\_PATH/tools/intel-minnow/environment-setup-core2-32-osv-linux}
+as a reference for creating your own environment\_setup file.
%%% Local Variables:
%%% mode: latex
@@ -1,23 +1,22 @@
\section{Introduction}
\label{sec:intro}
-Testing evaluation boards (and final products based on them) is not easy. There are is a number of software products made for that very purpose, the most eminent of which is \href{https://wiki.linaro.org/Platform/LAVA}{Lava}.
+Testing evaluation boards (and final products based on them) is not easy. There are a number of software products made for that very purpose, the most eminent of which is \href{https://wiki.linaro.org/Platform/LAVA}{Lava}.
-From our point of view, LAVA is harder to extend both in terms of engine and frontend. On the other hand, JTA core is based on shell scripts that can be trivially extended and uses Jenkins which is well tested and has lots of various plugins.
+From our point of view, LAVA is hard to extend both in terms of the engine and its frontend. On the other hand, the core of JTA is based on shell scripts that can be trivially extended and uses Jenkins which is well tested and has lots of available plugins to extend the framework with additional features (e.g. e-mail notification of test results).
-JTA framework was designed to provide a core meeting a few points:
+The JTA framework was designed to provide a core meeting a few points:
\begin{itemize}
-\item It is usable out of the box: 60+ prepackaged tests, benchmark statistics, plotting and reports generation.
-\item It is highly custmizable from front-end side (thanks to Jenkins that have tons of plugins) and from backend side, that relies on simple core written in bash, so that allows it to be easily customized;
-\item It allows for flexible test configuration using such notions as \textit{test specification} and \textit{test plan} \ref{sec:testplans};
-\item It allows to run a batch of tests and generate report \ref{sec:reports});
-\item It does not impose any demands on boards on distributions;
-\item It allows easy, yet flexible board setup. All you need is just to define some environment variables (block devices/mount points, IP addr etc) in board config file.
+\item It is usable out of the box: JTA includes 60+ prepackaged tests, including benchmark statistics, plotting and reports generation.
+\item It is highly custmizable on the front-end side (thanks to the availability of tons of plugins for Jenkins) and also on the backend side, which relies on a simple core written in bash;
+\item It allows for flexible test configuration using such notions as \textit{test specifications} and \textit{test plans} \ref{sec:testplans};
+\item It supports running groups of tests in a batch and generating reports \ref{sec:reports});
+\item It does not impose any demands on boards or distributions;
+\item It allows easy yet flexible board setup. All you need to do to add a new board is just define some environment variables (block devices/mount points, IP addr, etc.) in a board config file.
\end{itemize}
-
-As you can see, our goal is to provide flexible framework with seemless customization and out of box experience.
+As you can see, our goal is to provide a flexible framework with seemless customization and an easy out-of-the-box experience.
%%% Local Variables:
%%% mode: latex
new file mode 100755
@@ -0,0 +1,110 @@
+#!/bin/bash
+
+JTA_ENGINE_PATH=/home/jenkins
+JTA_FRONTEND_PATH=/var/lib/jenkins
+
+if [[ $EUID -ne 0 ]]; then
+ echo "This script must be run as root" 1>&2
+ exit 1
+fi
+
+if [ "$1" = "update-backend" ]
+then
+ echo "Updating backend and docs"
+ set -x
+ /etc/init.d/jenkins stop
+ cp -ar jta/engine/* $JTA_ENGINE_PATH/
+ # cp -ar jta/jenkins/* $JTA_FRONTEND_PATH/
+ # cp conf/jenkins.cfg /etc/default/jenkins
+ # cp conf/config.xml $JTA_FRONTEND_PATH/config.xml
+
+ # # fill in JTA_ENGINE_PATH_PLACEHOLDER with real value in all jenkins jobs
+ # find $JTA_FRONTEND_PATH -type f -exec sed -i "s#JTA_ENGINE_PATH_PLACEHOLDER#$JTA_ENGINE_PATH#" {} +
+
+ # # set global JTA_ENGINE_PATH global var in jenkins config
+ # sed -i "s#JTA_ENGINE_PATH_PLACEHOLDER#$JTA_ENGINE_PATH#" $JTA_FRONTEND_PATH/config.xml
+
+ cp docs/jta-guide.pdf $JTA_ENGINE_PATH/jta-docs.pdf
+
+ chown -R jenkins $JTA_ENGINE_PATH
+ # chown -R jenkins $JTA_FRONTEND_PATH
+
+ /etc/init.d/jenkins start
+ exit
+fi
+
+echo Installing prereqs...
+#echo deb http://ftp.us.debian.org/debian wheezy main non-free >> /etc/apt/sources.list
+apt-get update
+apt-get install daemon gcc make python-paramiko python-lxml python-simplejson python-matplotlib libtool xmlstarlet autoconf automake rsync openjdk-7-jre openjdk-7-jdk iperf netperf netpipe-tcp texlive-latex-base sshpass
+
+echo "adding multiarch support"
+#dpkg --add-architecture i386
+#apt-get update
+apt-get install ia32-libs
+
+# turn off dash as the default shell, this should switch the system to using
+# bash
+echo Please select NO in the following dialogue. Press return now.
+read
+dpkg-reconfigure dash
+
+echo Downloading and installing jenkins pkg...
+# wget http://ftp.vim.org/programming/jenkins/debian-stable/jenkins_1.509.2_all.deb
+dpkg -i install/jenkins_1.509.2_all.deb
+
+echo Installing stuff ...
+mkdir $JTA_ENGINE_PATH
+cp -ar jta/engine/* $JTA_ENGINE_PATH/
+cp -ar jta/jenkins/* $JTA_FRONTEND_PATH/
+cp conf/jenkins.cfg /etc/default/jenkins
+cp conf/config.xml $JTA_FRONTEND_PATH/config.xml
+
+# fill in JTA_ENGINE_PATH_PLACEHOLDER with real value in all jenkins jobs
+find $JTA_FRONTEND_PATH -type f -exec sed -i "s#JTA_ENGINE_PATH_PLACEHOLDER#$JTA_ENGINE_PATH#" {} +
+
+# set global JTA_ENGINE_PATH global var in jenkins config
+sed -i "s#JTA_ENGINE_PATH_PLACEHOLDER#$JTA_ENGINE_PATH#" $JTA_FRONTEND_PATH/config.xml
+
+ln -fns $JTA_ENGINE_PATH/logs $JTA_FRONTEND_PATH/userContent/jta.logs
+
+mkdir $JTA_ENGINE_PATH/work
+
+mkdir $JTA_ENGINE_PATH/docs
+cp docs/jta-guide.pdf $JTA_ENGINE_PATH/jta-docs.pdf
+
+wget "http://downloads.sourceforge.net/project/getfo/texml/texml-2.0.2/texml-2.0.2.tar.gz?r=http%3A%2F%2Fsourceforge.net%2Fprojects%2Fgetfo%2F&ts=1398789654&use_mirror=sunet" -O texml.tar.gz
+tar xvf texml.tar.gz
+cd texml-2.0.2
+python setup.py install
+cd -
+
+
+echo "fetching tools"
+git clone https://cogentembedded@bitbucket.org/cogentembedded/jta-tools-public.git tools
+mkdir $JTA_ENGINE_PATH/tools
+
+tools/osv-eglibc-x86_64-meta-toolchain-cortexa15hf-vfp-neon-toolchain-1.5+snapshot.sh -y -d $JTA_ENGINE_PATH/tools/renesas-arm
+tools/osv-eglibc-x86_64-meta-toolchain-core2-32-toolchain-1.5+snapshot.sh -y -d $JTA_ENGINE_PATH/tools/intel-minnow
+tools/osv-eglibc-x86_64-meta-toolchain-armv5te-toolchain-1.5+snapshot.sh -y -d $JTA_ENGINE_PATH/tools/qemu-arm
+
+chown -R jenkins $JTA_ENGINE_PATH
+chown -R jenkins $JTA_FRONTEND_PATH
+chown -R jenkins /var/cache/jenkins
+chown jenkins /etc/default/jenkins
+
+mkdir $JTA_ENGINE_PATH/overlays/work
+chown jenkins $JTA_ENGINE_PATH/overlays
+
+mkdir $JTA_ENGINE_PATH/logs/logruns
+chown jenkins $JTA_ENGINE_PATH/logs/logruns
+
+cp conf/jenkins.cfg /etc/default/jenkins
+
+echo Startings jenkins...
+/etc/init.d/jenkins start
+
+echo Installing custom frontend...
+cd install/jenkins-updates
+./updates.sh
+