OpenCL_helpers/documentation/tools_builder-english.tex

\subsection{Complete build routine}

\index{OpenCL builder}%
\index{oclh_br@\texttt{oclh\_br}}%
Complete build routine is performed by \verb|oclh_br|.

\subsubsection{Synopsis}

\begin{CodeParWithCC}{\\\{\}}
oclh_br [--dev-idxs=\underline{\smash{\textit{#}}},\underline{\smash{\textit{#}}},... | --dev-name=\underline{\smash{\textit{mask}}}]
        [--verbatim-output-name] [-o \underline{\smash{\textit{outfile}}}]
        [COMPILER_OPTIONS] [LINKER_OPTIONS] \underline{\smash{\textit{infile}}}...
\end{CodeParWithCC}

\subsubsection{Description}

When \verb|oclh_br| is called, a complete build routine (compilation and linking) of the source code from from files \verbIU{infile}\verb|...| is performed for all GPGPU devices available on the system. If the
\verb|--dev-idxs=|\verbIU{\#}\verb|,|\verbIU{\#}\verb|,...| option was
specified, then build would be performed only for the GPGPU devices with
the \verbIU{\#}\Verb|,|\verbIU{\#}\Verb|,...| indices (for details, see
s.\ref{subsubsec:br_args}). If the \verb|--dev-name=|\verbIU{mask} was
specified, then build would be performed only for the GPGPU devices whose
model matches the \verbIU{mask} (for details, see s.\ref{subsubsec:br_args}).

\begin{ImpNote}
At first glance, using the builder seems preferable than separate compilation
and linking, as it allows to get executable files from the source code for all
OpenCL devices at once. However, there are nuances that are related to the fact
that the work of the builder is determined by the library of the GPGPU device
vendor. So, during testing, the following problems were identified:\par
{\NmCnvDescript\noindent(1) not all builders support the generation of
libraries, most of them create an executable file, so to create exactly the
library, it is necessary to use the linker with the \verb|-create-library|
option (according to the current OpenCL specification);\par}
{\NmCnvDescript\noindent(2) for some unclear reason, some builders ignore the
declaration of a function and interpret only its definition, what leads to the
necessity of specifying files with the definition of the function in the
\verbIU{infile}\verb|...| list of files with source codes strictly before the
first use of the function, despite the declaration of the function in the
headers.\par}
\noindent Perhaps there are or will appear other pitfalls in using vendors'
builders, so it is recommended to use separate compilation and linking.
\end{ImpNote}

During the execution of the \verb|oclh_br| tool, a detailed diagnostic log is
being maintained in the \verb|oclh_br.log| file, where excessive information is
stored on all available GPGPU devices, used platforms, and contexts created for build. The log file format is described~in~s.\ref{subsec:logformat}.

Considering that build may be performed for several devices of different
vendors, the program build log is maintained in different log files
\verbIU{outfile}\verb|-|\verbI{GPGPU\_device\_model}\verb|-build.log|.

The result of the builder's work is an executable binary object saved in the
\verbIU{outfile}\verb|-|\verbI{GPGPU\_device\_model}\verb|.clexe| file. If
the option \verb|--verbatim-output-name| was specified, then the result would be
saved in the \verbIU{outfile} file. Sometimes a situation arises when the
vendor's OpenCL library generates several binary objects as a result, in which
case all binary objects will be saved, but the postfix \verb|.|\verbI{N} will be
added to the file names, where \verbI{N} is a decimal number denoting the
sequence number (starting from zero) of the binary object generated by the
builder of the vendor of the GPGPU device. An introduction to the file name of this number is due to the fact that, when implementing OpenCL, vendors are free to choose the output format of the built program. So, for example, the implementation from Intel will create and output a binary object, which is an ELF-file; and the NVidia's OpenCL implementation will output a human-readable text block of ptx-code (it's kind of Assembler variation for GPGPU, also named IR/IL~--~Intermediate Representation/Intermediate Language). Moreover, sometimes  several binary objects with different contents can be generated. Before saving, what exactly is contained in the binary object is not possible by OpenCL means, therefore binary objects are simply numbered by \verbI{N} in the order in which they are stored in memory by the OpenCL implementation.

If the option \verb|-o| is not specified, then the \verbIU{outfile} in the file
name will be replaced by a substring of the form \verb|program_0x|\verbI{HHHH}.
In case if the GPGPU device model is not identified by the OpenCL means, then
the \verbI{GPGPU\_device\_model} will be replaced by a substring of the form
\verb|dev_0x|\verbI{HHHH}. In the replacements mentioned above, \verbI{HHHH} is
hexadecimal representation of the last two bytes of the program and the GPGPU
device addresses, respectively. Given that addresses of the program and GPGPU
device are unique for one application run, it is highly likely that the
combination of the name of the instance and the last two bytes of its address is
also unique, so can be used as a substring to search related entries in the main
log file \verb|oclh_br.log|.

The main log file name \verb|oclh_br.log| and the file saving path can be
changed when building the OpenCL\_helpers library in the header file\\*
\indent\indent\verb|src/inc/oclh_settings.h|\\*
That name and the path to save logs and build results are defined in
macrodefinitions\\*
\indent\indent\verb|#define _GHM_LOG_PATH                  "."|\\*
\indent\indent\verb|#define _GHM_OCLH_BUILDER_LOG_FILENAME "oclh_br.log"|

The builder always receives the \verb|-D_OCLH_OCL_COMPILER_| argument. It is
hardcoded in the library code and introduced for ability to use header files
both in programs for GPGPU programs and CPU without changing them. For details,
see s.\ref{subsec:sharedheaders}.

\subsubsection{Arguments}
\label{subsubsec:br_args}

{\NmCnvDescript\verb|--dev-idxs=|\verbIU{\#}\Verb|,|\verbIU{\#}\verb|,...|\\*
the \verbIU{\#}\verb|,|\verbIU{\#}\verb|,...| numbers specified without spaces
separated by commas after the \verb|--dev-idxs=| option are sequence numbers
(indices) of GPGPU devices in the system for which the build will be performed.
Indices start with zero. You can find out the indice of a specific
device from the log file, in the first section of which in the device
description the first line has the form\par
{\hspace{2\leftskip}\verbI{YYYY}\verb|-|\verbI{MM}\verb|-|\verbI{DD}%
\verb| |\verbI{hh}\verb|:|\verbI{mm}\verb|:|\verbI{ss}%
\verb| ws_0x|\verbI{HHHH}\verb| dev_0x|\verbI{HHHH}%
\verb+ | Device index: +\verbI{N}},\par
\noindent where \verbI{N} -- is the indice of this device.\par}
{\NmCnvDescript\verb|--dev-name=|\verbIU{mask}\\* the \verbIU{mask} string
specified after the \verb|--dev-name=| option is a wildcard that defines which
device models present in the system the build will be performed for. Wildcard
characters are:\par
\hspace{2\leftskip}\verb|?| -- matches any single character;\par
\hspace{2\leftskip}\verb|*| -- matches any number of any characters including
none.\par
\noindent In the absence of wildcard characters the \verbIU{mask} is considered
to be the exact name of the device model. You can find out the model of a
specific device from the log file, in the first section of which in the device
description there is the line of the form\par
{\hspace{2\leftskip}\verbI{YYYY}\verb|-|\verbI{MM}\verb|-|\verbI{DD}%
\verb| |\verbI{hh}\verb|:|\verbI{mm}\verb|:|\verbI{ss}%
\verb| ws_0x|\verbI{HHHH}\verb| dev_0x|\verbI{HHHH}%
\verb+ | Device name: +\verbI{model}}\par
\noindent where \verbI{model} is the string that is checked for matching with
the \verbIU{mask}.\par}
{\NmCnvDescript\verb|--verbatim-output-name|\\*  the given option instructs the
builder not to add the GPGPU device model and an extension to the output file
name, but to use it exactly as described. But, if the result of the builder's
work was more than one binary object, then the \verb|.|\verbI{N} postfix would
be added to the file name, where \verbI{N} is decimal number denoting the
sequence number (starting from zero) of the binary object formed by the builder
of the GPGPU device vendor.\par}
{\NmCnvDescript\verb|-o |\verbIU{outfile}\\* the \verbIU{outfile} string is the
name of the output file. If the \verb|--verbatim-output-name| option was not
specified, then the \verbIU{outfile} string would be used as the prefix of the
\verbIU{outfile}\verb|-|\verbI{GPGPU\_device\_model}\verb|.clexe| file name,
which contains the binary object generated as the result of build. If the
\verb|--verbatim-output-name| option was specified, then the \verbIU{outfile}
string would be used <<as is>>, unless several binary objects was generated as
result of build~--~in this case, all binary objects would be saved with
the \verbIU{outfile}\verb|.|\verbI{N} file names, where \verbI{N} is the
sequence number of the binary object starting from zero. Additionally, the
\verbIU{outfile} string is used as the prefix in the name of the build log
file.\par
\begin{ImpNote}
Space characters at the beginning and the end of the \verbIU{outfile} string are
deleted. Space characters inside of the \verbIU{outfile} string are replaced
with underscores.
\end{ImpNote}
}
{\NmCnvDescript\verb|COMPILER_OPTIONS|\\* compiler arguments. In unchanged form
and with the preservation of the sequence passed to the builder of the vendor.
The compiler arguments themselves are described in the OpenCL specifications, in
addition, the vendor's builder can support additional arguments not fixed in
the OpenCL specifications.\par}
{\NmCnvDescript\verb|LINKER_OPTIONS|\\* linker arguments. In unchanged form
and with the preservation of the sequence passed to the builder of the vendor.
The linker arguments themselves are described in the OpenCL specifications, in
addition, the vendor's builder can support additional arguments not fixed in
the OpenCL specifications.\par}
{\NmCnvDescript\verbIU{infile}\verb|...|\\* the list separated by spaces with
the names of the files containing the source code of the OpenCL C or OpenCL C++
program. The file name cannot begin with a~<<\verb|-|>>~character.\par}