<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<chapter xml:id="mysql-xdevapi.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.setup;

 <section xml:id="mysql-xdevapi.requirements">
  &reftitle.required;
  <para>
   This extension requires a MySQL 8+ server with the X plugin 
   enabled (default).
  </para>
  <para>
   Prerequisite libraries for compiling this extension are: 
   Boost (1.53.0 or higher), OpenSSL, and Protobuf.
  </para>

 </section>

 <section xml:id="mysql-xdevapi.installation">
  &reftitle.install;

  <para>
   &pecl.moved;
  </para>

  <para>
   An example installation procedure on Ubuntu 18.04 with PHP 7.2:
  </para>
<programlisting>
<![CDATA[
// Dependencies
$ apt install build-essential libprotobuf-dev libboost-dev openssl protobuf-compiler liblz4-tool zstd

// PHP with the desired extensions; php7.2-dev is required to compile
$ apt install php7.2-cli php7.2-dev php7.2-mysql php7.2-pdo php7.2-xml

// Compile the extension
$ pecl install mysql_xdevapi
]]>
</programlisting>

  <para>
    The <literal>pecl install</literal> command does not enable PHP extensions (by default)
    and enabling PHP extensions can be done in several ways. 
    Another PHP 7.2 on Ubuntu 18.04 example:
  </para>

<programlisting>
<![CDATA[
// Create its own ini file
$ echo "extension=mysql_xdevapi.so" > /etc/php/7.2/mods-available/mysql_xdevapi.ini

// Use the 'phpenmod' command (note: it's Debian/Ubuntu specific)
$ phpenmod -v 7.2 -s ALL mysql_xdevapi

// A 'phpenmod' alternative is to manually symlink it
// $ ln -s /etc/php/7.2/mods-available/mysql_xdevapi.ini /etc/php/7.2/cli/conf.d/20-mysql_xdevapi.ini

// Let's see which MySQL extensions are enabled now
$ php -m |grep mysql

mysql_xdevapi
mysqli
mysqlnd
pdo_mysql
]]>
</programlisting>

  <para>
   &pecl.info;
   <link xlink:href="&url.pecl.package;mysql_xdevapi">&url.pecl.package;mysql_xdevapi</link>.
  </para>
 </section>

 <!-- {{{ Configuration -->
 &reference.mysql-xdevapi.ini;
 <!-- }}} -->

  <section xml:id="mysql-xdevapi.build">
   <title>Building / Compiling From Source</title>
   <para>
     Considerations for compiling this extension from source.
   </para>

    <itemizedlist>
      <listitem>
        <para>
          The extension name is 'mysql_xdevapi', so use <literal>--enable-mysql-xdevapi</literal>.
        </para>
      </listitem>
      <listitem>
        <para>
          Boost: required,  optionally use the --with-boost=DIR configure option
          or set the MYSQL_XDEVAPI_BOOST_ROOT environment variable. Only the
          boost header files are required; not the binaries.
        </para>
      </listitem>
      <listitem>
        <para>
          Google Protocol Buffers (protobuf): required,  optionally use the --with-protobuf=DIR
          configure option or set the MYSQL_XDEVAPI_PROTOBUF_ROOT environment variable.
        </para>
        <para>
          Optionally use <literal>make protobufs</literal> to generate protobuf files (*.pb.cc/.h),
          and <literal>make clean-protobufs</literal> to delete generate protobuf files.
        </para>
        <para>
          Windows specific protobuf note: depending on your environment,
          the static library with a multi-threaded DLL runtime may be needed.
          To prepare, use the following options:
          <emphasis>-Dprotobuf_MSVC_STATIC_RUNTIME=OFF -Dprotobuf_BUILD_SHARED_LIBS=OFF</emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
          Google Protocol Buffers / protocol compiler (protoc): required, ensure that proper
          'protoc' is available in the PATH while building. It is especially
          important as Windows PHP SDK batch scripts may overwrite the environment.
        </para>
      </listitem>
        <listitem>
          <para>
            Bison: required, and available from the PATH.
          </para>
          <para>
            Windows specific bison note: we strongly recommended that bison delivered with the
            chosen PHP SDKis used else an error similar to "zend_globals_macros.h(39):
            error C2375: 'zendparse': redefinition; different linkage
            Zend/zend_language_parser.h(214): note: see declaration of 'zendparse'" may
            be the result. Also, Windows PHP SDK batch scripts may overwrite the environment.
          </para>
        </listitem>
      <listitem>
        <para>
          Windows Specific Notes: To prepare the environment, see the official
          Windows build documentation for 
          <link xlink:href="&url.php.win.build2;">the current SDK</link>.
        </para>
        <para>
          We recommend using the backslash '\\' instead of a slash '/' for all paths.
        </para>
      </listitem>
    </itemizedlist>
  </section>
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->