<!-- buildOptionsInc.xml, section 5.6.4 -->

    <bridgehead>Compiler Options</bridgehead>

    <para>
      The compiler options are categorized as pre-processor options, options for math intrinsics,
      options that control optimization and miscellaneous options. This specification defines
      a standard set of options that must be supported by the OpenCL C compiler when building
      program executables online or offline. These may be extended by a set of vendor- or
      platform specific options.
    </para>

    <bridgehead>Preprocessor Options</bridgehead>

    <para>
      These options control the OpenCL C preprocessor which is run on each program source before
      actual compilation.
    </para>

    <para>
      -D options are processed in the order they are given in the 
      <varname>options</varname> argument to
      <function>clBuildProgram</function> or <function>clCompileProgram</function>.
    </para>

    <variablelist>
        <varlistentry>
            <term>-D name</term>
            <listitem>
                <para>
                  Predefine <varname>name</varname> as a macro, with definition 1.
                </para>
           </listitem>
        </varlistentry>

        <varlistentry>
            <term>-D name=definition</term>
            <listitem>
                <para>
                  The contents of <varname>definition</varname> are tokenized and processed as
                  if they appeared during translation phase three in a '#define' directive. In
                  particular, the definition will be truncated by embedded newline characters.
                </para>
           </listitem>
        </varlistentry>

        <varlistentry>
            <term>-I dir</term>
            <listitem>
                <para>
                  Add the directory <varname>dir</varname> to the list of directories to be
                  searched for header files.
                </para>
           </listitem>
        </varlistentry>
    </variablelist>

    <bridgehead>Math Intrinsics Options</bridgehead>

    These options control compiler behavior regarding floating-point arithmetic. These options trade
    off between speed and correctness.

    <variablelist>
        <varlistentry>
            <term>-cl-single-precision-constant</term>
            <listitem>
                <para>
                  Treat double precision floating-point constant as single precision constant.
                </para>
           </listitem>
        </varlistentry>

        <varlistentry>
            <term>-cl-denorms-are-zero</term>
            <listitem>
                <para>
                  This option controls how single precision and double precision denormalized
                  numbers are handled. If specified as a build option, the single precision
                  denormalized numbers may be flushed to zero; double precision denormalized
                  numbers may also be flushed to zero if the optional extension for double
                  precsion is supported.  This is intended to be a performance hint and the
                  OpenCL compiler can choose not to flush denorms to zero if the device supports
                  single precision (or double precision) denormalized numbers.
                </para>

                <para>
                  This option is ignored for single precision numbers if the
                  device does not support single precision denormalized numbers
                  i.e. <constant>CL_FP_DENORM</constant> bit is not set in
                  <constant>CL_DEVICE_SINGLE_FP_CONFIG</constant>.
                </para>

                <para>
                  This option is ignored for double precision numbers if the device
                  does not support double precision or if it does support double
                  precison but not double precision denormalized 
                  numbers i.e. <constant>CL_FP_DENORM</constant> bit is not set in
                  <constant>CL_DEVICE_DOUBLE_FP_CONFIG</constant>.
                </para>

                <para>
                  This flag only applies for scalar and vector single precision floating-point
                  variables and computations on these floating-point variables inside a
                  program. It does not apply to reading from or writing to image objects.
                </para>
           </listitem>
        </varlistentry>

        <varlistentry>
            <term>-cl-fp32-correctly-rounded-divide-sqrt</term>
            <listitem>
                <para>
                  The <code>-cl-fp32-correctly-rounded-divide-sqrt</code> build option to
                  <function>clBuildProgram</function> or <function>clCompileProgram</function>
                  allows an application to specify that single precision floating-point divide
                  (x/y and 1/x) and sqrt used in the program source are correctly rounded.
                  If this build option is not specified, the minimum numerical accuracy of
                  single precision floating-point divide and sqrt are as defined in section
                  7.4 of the OpenCL specification.
                </para>

                <para>
                  This build option can only be specified if the
                  <constant>CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT</constant> is set
                  in <constant>CL_DEVICE_SINGLE_FP_CONFIG</constant> (as defined in
                  in the table of allowed values for <varname>param_name</varname> for
                  <citerefentry><refentrytitle>clGetDeviceInfo</refentrytitle></citerefentry>) for
                  devices that the program is being build.  <function>clBuildProgram</function>
                  or <function>clCompileProgram</function> will fail to compile the program for
                  a device if the <code>-cl-fp32-correctly-rounded-divide-sqrt</code> option is specified
                  and <constant>CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT</constant> is not set for
                  the device.
                </para>
           </listitem>
        </varlistentry>
    </variablelist>

    <bridgehead>Optimization Options</bridgehead>

    <para>
      These options control various sorts of optimizations. Turning on optimization flags
      makes the compiler attempt to improve the performance and/or code size at the expense of
      compilation time and possibly the ability to debug the program.
    </para>

    <variablelist>
        <varlistentry>
            <term>-cl-opt-disable</term>
            <listitem>
                <para>
                  This option disables all optimizations. The default is optimizations are enabled.
                </para>
        </listitem> </varlistentry>
    </variablelist>

    <para>
      The following options control compiler behavior regarding floating-point arithmetic. These
      options trade off between performance and correctness and must be specifically enabled.
      These options are not turned on by default since it can result in incorrect output for
      programs which depend on an exact implementation of IEEE 754 rules/specifications for
      math functions.
    </para>

    <variablelist>
        <varlistentry>
            <term>-cl-mad-enable</term>
            <listitem>
                <para>
                  Allow <code>a * b + c</code> to be replaced by a <code>mad</code>. The
                  <code>mad</code> computes <code>a * b + c</code> with reduced accuracy. For
                  example, some OpenCL devices implement <code>mad</code> as truncate the result
                  of <code>a * b</code> before adding it to <code>c</code>.
                </para>
            </listitem> 
        </varlistentry>

        <varlistentry>
            <term>-cl-no-signed-zeros</term>
            <listitem>
                <para>
                  Allow optimizations for floating-point arithmetic that ignore the signedness of
                  zero. IEEE 754 arithmetic specifies the distinct behavior of <code>+0.0</code>
                  and <code>-0.0</code> values, which then prohibits simplification of expressions
                  such as <code>x+0.0</code> or <code>0.0*x</code> (even with <code>-clfinite-math</code>
                  only). This option implies that the sign of a zero result isn't significant.
                </para>
        </listitem> </varlistentry>

        <varlistentry>
            <term>-cl-unsafe-math-optimizations</term>
            <listitem>
                <para>
                  Allow optimizations for floating-point arithmetic that (a) assume that
                  arguments and results are valid, (b) may violate IEEE 754 standard and (c)
                  may violate the OpenCL numerical compliance requirements as defined in section
                  7.4 for single precision and double precision floating-point, and edge case
                  behavior in section 7.5.  This option includes the <code>-cl-no-signed-zeros</code> and
                  <code>-cl-mad-enable</code> options.
                </para>
        </listitem> </varlistentry>

        <varlistentry>
            <term>-cl-finite-math-only</term>
            <listitem>
                <para>
                  Allow optimizations for floating-point arithmetic that assume that arguments and
                  results are not NaNs or &#x000B1;&#x0221E;. This option may violate the OpenCL
                  numerical compliance requirements defined in section 7.4 for single precision
                  and double precision floating point, and edge case behavior in section 7.5.
                </para>
        </listitem> </varlistentry>

        <varlistentry>
            <term>-cl-fast-relaxed-math</term>
            <listitem>
                <para>
                  Sets the optimization options <code>-cl-finite-math-only</code> and
                  <code>-cl-unsafe-math-optimizations</code>.  This allows optimizations for floating-point
                  arithmetic that may violate the IEEE 754 standard and the OpenCL numerical
                  compliance requirements defined in the specification in section 7.4 for
                  single-precision and double precision floating-point, and edge case
                  behavior in section 7.5. This option also relaxes the precision of commonly 
                    used math functions (refer to 
                    table 7.2 defined in section 7.4). 
                    This option causes the preprocessor macro
                  <code>__FAST_RELAXED_MATH__</code> to be defined in the OpenCL program.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>-cl-uniform-work-group-size</term>
            <listitem>
                <para>
                    This requires that the global work-size be 
                    a multiple of the work-group size specified to 
                    <citerefentry><refentrytitle>clEnqueueNDRangeKernel</refentrytitle></citerefentry>.
                    Allow optimizations that are made possible by this restriction.
                </para>
            </listitem>
        </varlistentry>

    </variablelist>

    <bridgehead>Options to Request or Suppress Warnings</bridgehead>

    Warnings are diagnostic messages that report constructions which are not inherently erroneous
    but which are risky or suggest there may have been an error. The following language independent
    options do not enable specific warnings but control the kinds of diagnostics
    produced by the OpenCL compiler.

    <variablelist>
        <varlistentry>
            <term>-w</term>
            <listitem>
                <para>
                  Inhibit all warning messages.
                </para>
           </listitem>
        </varlistentry>

        <varlistentry>
            <term>-Werror</term>
            <listitem>
                <para>
                  Make all warnings into errors.
                </para>
           </listitem>
        </varlistentry>
    </variablelist>

    <bridgehead>Options Controlling the OpenCL C Version</bridgehead>

    The following option controls the version of OpenCL C that the compiler accepts.

    <variablelist>
        <varlistentry>
            <term>-cl-std=</term>
            <listitem>
                <para>
                  Determine the OpenCL C language version to use. A value for this option must
                  be provided. Valid values are:
                </para>

                <para>
                  <code>CL1.1</code> - Support all OpenCL C programs that use the OpenCL C language features
                  defined in section 6 of the OpenCL 1.1 specification.
                </para>

                <para>
                  <code>CL1.2</code> - Support all OpenCL C programs that use the OpenCL C language features
                  defined in section 6 of the OpenCL 1.2 specification.
                </para>

                <para>
                  <code>CL2.0</code> - Support all OpenCL C programs that use the OpenCL C language features
                  defined in section 6 of the OpenCL 2.0 specification.
                </para>
           </listitem>
        </varlistentry>
    </variablelist>

    <para>
      Calls to <function>clBuildProgram</function> or <function>clCompileProgram</function> with
      the <code>-cl-std=CL1.1</code> option will fail to compile the program for any devices with
      <constant>CL_DEVICE_OPENCL_C_VERSION</constant> = OpenCL C 1.0.  
    </para>

    <para>
      Calls to <function>clBuildProgram</function> or <function>clCompileProgram</function> with
      the <code>-cl-std=CL1.2</code> option will fail to compile the program for any devices with
      <constant>CL_DEVICE_OPENCL_C_VERSION</constant> = OpenCL C 1.0 or OpenCL C 1.1.
    </para>

    <para>
      Calls to <function>clBuildProgram</function> or <function>clCompileProgram</function> with
      the <code>-cl-std=CL2.0</code> option will fail to compile the program for any devices with
      <constant>CL_DEVICE_OPENCL_C_VERSION</constant> = OpenCL C 1.0, OpenCL C 1.1, or OpenCL C 1.2.
    </para>

    <para>
        If the <code>–cl-std</code> build option is not specified, the 
        highest OpenCL C 1.x language version supported 
        by each device is used when compiling the program 
        for each device. Applications are required 
        to specify the <code>–cl-std=CL2.0</code> option if they want 
        to compile or build their programs with 
        OpenCL C 2.0.
    </para>

    <bridgehead>Options enabled by the cl_khr_spir extension</bridgehead>

    <variablelist>
        <varlistentry>
            <term>-x spir</term>
            <listitem>
                <para>
                    Indicates that the binary is in SPIR format.
                </para>
           </listitem>
        </varlistentry>
    </variablelist>

    <variablelist>
        <varlistentry>
            <term>-spir-std</term>
            <listitem>
                <para>
                    Specifies the version of the SPIR specification that 
                    describes the format and meaning of the binary. For 
                    example, if the binary is as described in 
                    SPIR version 1.2, then <code>-spir-std=1.2</code> must 
                    be specified. Failing to specify these compile options 
                    may result in implementation defined behavior.
                </para>
           </listitem>
        </varlistentry>
    </variablelist>

    <bridgehead>Options for Querying Kernel Argument Information</bridgehead>

    <variablelist>
        <varlistentry>
            <term>-cl-kernel-arg-info</term>
            <listitem>
                <para>
                  This option allows the compiler to store information about the
                  arguments of a kernel(s) in the program executable.  The argument
                  information stored includes the argument name, its type,
                  the address and access qualifiers used.  Refer to description of
                  <citerefentry><refentrytitle>clGetKernelArgInfo</refentrytitle></citerefentry>
                  on how to query this information.
                </para>
            </listitem>
        </varlistentry>
    </variablelist>

    <bridgehead>Options for debugging your program</bridgehead>

    <variablelist>
        <varlistentry>
            <term>-g</term>
            <listitem>
                <para>
                    This option can currently be used to generate 
                    additional errors for the built-in functions
                    that allow you to enqueue commands on a device 
                    (refer to section 6.13.17).
                </para>
            </listitem>
        </varlistentry>
    </variablelist>

    <bridgehead>Linker Options</bridgehead>

    This specification defines a standard set of linker options that must be supported by the
    OpenCL C compiler when linking compiled programs online or offline. These linker options
    are categorized as library linking options and program linking options. These may be
    extended by a set of vendor- or platform-specific options.

    <bridgehead>Library Linking Options</bridgehead>

    The following options can be specified when creating a library of compiled binaries.

    <variablelist>
        <varlistentry>
            <term>-create-library</term>
            <listitem>
                <para>
                  Create a library of compiled binaries specified
                  in <varname>input_programs</varname> argument to
                  <citerefentry><refentrytitle>clLinkProgram</refentrytitle></citerefentry>.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term>-enable-link-options</term>
            <listitem>
                <para>
                  Allows the linker to modify the library behavior based on one or more link
                  options (described in Program Linking Options, below) when this library is
                  linked with a program executable. This option must be specified with the
                  <code>-create-library</code> option.
                </para>
            </listitem>
        </varlistentry>
    </variablelist>

    <bridgehead>Program Linking Options</bridgehead>

    The following options can be specified when linking a program executable.

    <itemizedlist mark="disc">
        <listitem> <code>-cl-denorms-are-zero</code> </listitem>
        <listitem> <code>-cl-no-signed-zeroes</code> </listitem>
        <listitem> <code>-cl-unsafe-math-optimizations</code> </listitem>
        <listitem> <code>-cl-finite-math-only</code> </listitem>
        <listitem> <code>-cl-fast-relaxed-mat</code> </listitem>
    </itemizedlist>

    The linker may apply these options to all compiled program objects specified to
    <citerefentry><refentrytitle>clLinkProgram</refentrytitle></citerefentry>. The linker
    may apply these options only to libraries which were created with the 
    <code>-enable-link-option</code>.

    <bridgehead>Separate Compilation and Linking of Programs</bridgehead>

    <para>
      OpenCL programs are compiled and linked to support the following:
    </para>

    <itemizedlist mark="disc">
        <listitem>
          Separate compilation and link stages.  Program sources can be compiled to generate
          a compiled binary object and linked in a separate stage with other compiled program
          objects to the program exectuable.
        </listitem>

        <listitem>
          Embedded headers.  In OpenCL 1.0 and 1.1, the <code>-I</code> build option could be used to
          specify the list of directories to be searched for headers files that are included
          by a program source(s).  OpenCL 1.2 extends this by allowing the header sources to
          come from program objects instead of just header files.
        </listitem>

        <listitem>
          Libraries.  The linker can be used to link compiled objects and libraries into a
          program executable or to create a library of compiled binaries.
        </listitem>
    </itemizedlist>

<!-- 23-Dec-2013, rev. 19 -->