<!--
Copyright © 2017 Collabora Ltd
SPDX-License-Identifier: LGPL-2.1-or-later

This file is part of libcapsule.

libcapsule is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation; either version 2.1 of the
License, or (at your option) any later version.

libcapsule is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with libcapsule.  If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="capsule-mkstublib">

  <refentryinfo>
    <title>capsule-mkstublib</title>
    <productname>libcapsule</productname>
    <authorgroup>
      <author>
        <contrib>Developer</contrib>
        <firstname>Vivek</firstname>
        <surname>Das Mohapatra</surname>
      </author>
      <author>
        <contrib>Developer</contrib>
        <firstname>Simon</firstname>
        <surname>McVittie</surname>
      </author>
    </authorgroup>
  </refentryinfo>

  <refmeta>
    <refentrytitle>capsule-mkstublib</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="manual">User Commands</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>capsule-mkstublib</refname>

    <refpurpose>
      Command used by the libcapsule build system to generate proxy
      library source files.
    </refpurpose>

  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>capsule-mkstublib</command>
      <arg choice="opt">OPTIONS</arg>
      <arg choice="plain">TARGET</arg>
      <arg choice="plain">EXCLUDES</arg>
      <arg choice="plain">EXPORTS</arg>
      <arg choice="plain">OUTPUT</arg>
      <arg choice="opt">DSO-VERSION<arg choice="opt">TREE</arg></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      <command>capsule-mkstublib</command> generates the source code
      for a libcapsule proxy library from a standard set of inputs
      (described below).
    </para>
  </refsect1>

  <refsect1>
    <title>Arguments</title>
    <variablelist>

      <varlistentry>
        <term><option>TARGET</option></term>
        <listitem>
          <para>
            The SONAME of the target, of the form libFOO.so.X (eg libz.so.1)
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>EXCLUDES</option></term>
        <listitem>
          <para>
            A file containing a list of SONAMEs (one on each line) not to
            include in the libcapsule proxy: DSOs listed here will not
            be loaded from the foreign tree and must come from the
            normal set searched by the linker.
          </para>
          <para>
            For example if libz.so.1 is listed here, and TARGET depends
            on libz.so.1 then it will be run-time linked against the
            copy of libz from / - not any copies which are found under TREE
          </para>
          <para>
            This file is empty by default in new prjects.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>EXPORTS</option></term>
        <listitem>
          <para>
            A file containing a list of SONAMEs (one on each line) whose
            symbols should be exported.
          </para>
          <para>Symbols from TARGET are always exported.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>OUTPUT</option></term>
        <listitem>
          <para>
            Output filename
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>DSO-VERSION</option></term>
        <listitem>
          <para>
            The version of the target library our proxy will pretend to be,
            in the format MAJOR:MINOR:SUB
          </para>
          <para>
            The format is the same format as consumed by libtool.
            Only MAJOR must be present if this argument is supplied.
          </para>
          <para>
            The default value is determined by parsing the soname of the
            library.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>TREE</option></term>
        <listitem>
          <para>
            The mount point of the foreign filesystem tree from which TARGET
            and its dependencies will be acquired.
          </para>
          <para>
            This value can be overridden by --runtime-tree and --search-tree.
          </para>
          <para>
            The default is the soname-specific environment variable (eg
            CAPSULE_LIBGL_SO_1_PREFIX for libGL.so.1), or the CAPSULE_PREFIX
            environment variable, or /host. The environment variables are
            ignored if the process is privileged, or if libcapsule was
            compiled with glibc older than 2.17.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
    
  </refsect1>

  <refsect1>
    <title>Options</title>
    <variablelist>

      <varlistentry>
        <term><option>--capsule-symbols-tool=PATH</option></term>
        <listitem>
          <para>Use replacement capsule-symbols(1)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--symbols-from=PATH</option></term>
        <listitem>
          <para>
            Use this symbols file instead of the output of capsule-symbols(1)
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--[no]-update-symbols</option></term>
        <listitem>
          <para>
            Do or don't update the exported symbol list if EXPORTS is
            updated [default: do]
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--search-tree=PATH</option></term>
        <listitem>
          <para>
            Find libraries to be proxied in this chroot,
            sysroot or container at compile-time.
          </para>
          <para>default: TREE or / if unset</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--runtime-tree=PATH</option></term>
        <listitem>
          <para>
            Find libraries to be proxied in this chroot, sysroot or
            container at runtime. The default is /host.
          </para>
          <para>
            If libcapsule was compiled with glibc 2.17 or later and the
            process is not privileged, this can be overridden at runtime
            by setting a SONAME-specific environment variable (for
            example CAPSULE_LIBGL_SO_1_PREFIX for libGL.so.1) or by
            setting the generic CAPSULE_PREFIX environment variable.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1>
    <title>Bugs</title>
    <para>
      The order of arguments is a bit pathological: This is for
      historical reasons. Since the command is not expected to be
      invoked outside of libcapsule's build scripts this is not
      considered a major problem.
    </para>
  </refsect1>
  
  <refsect1>
    <title>See also</title>
    <para>
      <citerefentry>
        <refentrytitle>capsule-init-project</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>
    </para>
  </refsect1>
</refentry>
