source: general/prog/llvm.xml@ 4c44c67

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY llvm-download-http "http://llvm.org/releases/&llvm-version;/llvm-&llvm-version;.src.tar.xz">
  <!ENTITY llvm-download-ftp  " ">
  <!ENTITY llvm-md5sum        "bf8b3a2c79e61212c5409041dfdbd319">
  <!ENTITY llvm-size          "14 MB">
  <!ENTITY llvm-buildsize     "1.6 GB (with Clang and tests)">
  <!ENTITY llvm-time          "13 SBU (with Clang, tests and parallelism = 4)">

  <!ENTITY clang-download-http "http://llvm.org/releases/&llvm-version;/cfe-&llvm-version;.src.tar.xz">
  <!ENTITY clang-md5sum        "0acd026b5529164197563d135a8fd83e">
  <!ENTITY clang-size          " 8.7 MB">

  <!ENTITY rt-version                "&llvm-version;">
  <!ENTITY compiler-rt-download-http "http://llvm.org/releases/&rt-version;/compiler-rt-&rt-version;.src.tar.xz">
  <!ENTITY compiler-rt-md5sum        "1c6975daf30bb3b0473b53c3a1a6ff01">
  <!ENTITY compiler-rt-size          "1.2 MB">
]>

<sect1 id="llvm" xreflabel="LLVM-&llvm-version;">
  <?dbhtml filename="llvm.html" ?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>LLVM-&llvm-version;</title>

  <indexterm zone="llvm">
    <primary sortas="a-LLVM">LLVM</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to LLVM</title>

    <para>
      The <application>LLVM</application> package contains a collection of
      modular and reusable compiler and toolchain technologies. The Low Level
      Virtual Machine (LLVM) Core libraries provide a modern source and
      target-independent optimizer, along with code generation support for many
      popular CPUs (as well as some less common ones!). These libraries are
      built around a well specified code representation known as the LLVM
      intermediate representation ("LLVM IR").
    </para>

    <para>
      The optional <application>Clang</application> and <application>Compiler
      RT</application> packages provide a new C, C++, Objective C and Objective
      C++ front-ends and runtime libraries for the
      <application>LLVM</application>.
    </para>

    <note>
      <para>
        This package hits a bug in GCC-4.9.0 or an unpatched GCC-4.9.1.
        To build this package, GCC needs to be updated if you have one of
        these versions. See <xref linkend="gcc"/>
        for <application>gcc</application> installation instructions.
      </para>
    </note>

    &lfs78_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&llvm-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&llvm-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &llvm-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &llvm-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &llvm-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &llvm-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Optional Downloads</bridgehead>

      <bridgehead renderas="sect4">Clang</bridgehead>
      <itemizedlist spacing="compact">
        <listitem>
          <para>
            Download: <ulink url="&clang-download-http;"/>
          </para>
        </listitem>
        <listitem>
          <para>
            Download MD5 sum: &clang-md5sum;
          </para>
        </listitem>
        <listitem>
          <para>
            Download size: &clang-size;
          </para>
        </listitem>
      </itemizedlist>

      <bridgehead renderas="sect4">Compiler RT</bridgehead>
      <itemizedlist spacing="compact">
        <listitem>
          <para>
            Download: <ulink url="&compiler-rt-download-http;"/>
          </para>
        </listitem>
        <listitem>
          <para>
            Download MD5 sum: &compiler-rt-md5sum;
          </para>
        </listitem>
        <listitem>
          <para>
            Download size: &compiler-rt-size;
          </para>
        </listitem>
      </itemizedlist>

    <bridgehead renderas="sect3">LLVM Dependencies</bridgehead>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="libffi"/> and
      <xref linkend="python2"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="cmake"/>,
      <xref linkend="doxygen"/>,
      <xref linkend="graphviz"/>,
      <xref linkend="libxml2"/>,
      <xref linkend="texlive"/> (or <xref linkend="tl-installer"/>),
      <xref linkend="valgrind"/>,
      <xref linkend="zip"/>,
      <ulink url="http://www.ocaml.org/">OCaml</ulink>, and
      <ulink url="http://pypi.python.org/pypi/Sphinx">Sphinx</ulink>
    </para>

    <para condition="html" role="usernotes">User Notes:
      <ulink url="&blfs-wiki;/llvm"/>
    </para>
  </sect2>

  <sect2 role="installation">
    <title>Installation of LLVM</title>

    <para>
      If you have downloaded the optional packages, install them into
      the source tree by running the following commands:
    </para>

<screen><userinput>tar -xf ../cfe-&llvm-version;.src.tar.xz -C tools &amp;&amp;
tar -xf ../compiler-rt-&rt-version;.src.tar.xz -C projects &amp;&amp;

mv tools/cfe-&llvm-version;.src tools/clang &amp;&amp;
mv projects/compiler-rt-&rt-version;.src projects/compiler-rt</userinput></screen>

<!-- Only for 3.7.0: hopefully fixed on later versions -->
    <para>
      The run-time library needs to be fixed for 32 bit installations:
    </para>

<screen><userinput>sed -r "/ifeq.*CompilerTargetArch/s#i386#i686#g" \
    -i projects/compiler-rt/make/platform/clang_linux.mk</userinput></screen>

    <para>
      Install <application>LLVM</application> by running the following
      commands:
    </para>

<screen><userinput>sed -e "s:/docs/llvm:/share/doc/llvm-&llvm-version;:" \
    -i Makefile.config.in &amp;&amp;

mkdir -v build &amp;&amp;
cd       build &amp;&amp;

CC=gcc CXX=g++                          \
../configure --prefix=/usr              \
             --datarootdir=/usr/share   \
             --sysconfdir=/etc          \
             --enable-libffi            \
             --enable-optimized         \
             --enable-shared            \
             --enable-targets=host,r600 \
             --disable-assertions       \
             --docdir=/usr/share/doc/llvm-&llvm-version; &amp;&amp;
make</userinput></screen>

    <para>
      If you have installed <application>Sphinx</application> and wish
      to generate manual pages, issue the following command:
    </para>

<screen><userinput>make -C ../docs -f Makefile.sphinx man</userinput></screen>

    <para>
      To test the results, issue: <command>make -k check-all</command>.
      Some tests may fail for unknown reasons.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install &amp;&amp;

for file in /usr/lib/lib{clang,LLVM,LTO}*.a
do
  test -f $file &amp;&amp; chmod -v 644 $file
done
unset file</userinput></screen>

    <para>
      If you had <xref linkend="python2"/> installed and you have
      built <application>Clang</application>, install the
      <application>Clang Analyzer</application> by running the
      following command as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>install -v -dm755 /usr/lib/clang-analyzer &amp;&amp;

for prog in scan-build scan-view
do
  cp -rfv ../tools/clang/tools/$prog /usr/lib/clang-analyzer/ &amp;&amp;
  ln -sfv ../lib/clang-analyzer/$prog/$prog /usr/bin/
done
unset prog &amp;&amp;

ln -sfv /usr/bin/clang \
        /usr/lib/clang-analyzer/scan-build/ &amp;&amp;
mv -v   /usr/lib/clang-analyzer/scan-build/scan-build.1 \
        /usr/share/man/man1/</userinput></screen>

    <para>
      If you have built manual pages, install them by running the
      following command as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>install -v -m644 ../docs/_build/man/* /usr/share/man/man1/</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <command>sed -e ... Makefile.config.in</command>: This sed fixes
      location of the installed documentation.
    </para>

    <para>
      <parameter>--enable-libffi</parameter>: This switch enables
      <application>LLVM</application> to use
      <application>libffi</application>. Remove if you did not
      install <application>libffi</application>.
    </para>

    <para>
      <parameter>--enable-optimized</parameter>: This switch enables
      compiler optimizations in order to speed up the code and reduce
      its size.
    </para>

    <para>
      <parameter>--enable-shared</parameter>: This switch enables
      building of the <application>LLVM</application> shared
      library which contains all of the static libraries linked into
      a single library.
    </para>

    <para>
      <parameter>--enable-targets=host,r600</parameter>: This switch enables
      building for the same target as the host, and also for the r600 AMD GPU
      used by the Mesa r600 and radeonsi drivers. Default is all. You can use
      a comma separated list. Valid targets are: host, x86, x86_64, sparc,
      powerpc, arm64, arm, aarch64, mips, hexagon, xcore, msp430, nvptx,
      systemz, r600, amdgpu (equivalent to r600), bpf, wasm, and cpp.
    </para>

    <para>
      <parameter>--disable-assertions</parameter>: Disable some compile checks,
      not necessary on a production system.
    </para>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          bugpoint, c-index-test, clang, clang++ (symlink), count, FileCheck,
          clang-check, clang-format, clang-tblgen, llc, lli, lli-child-target,
          llvm-ar, llvm-as, llvm-bcanalyzer, llvm-config, llvm-cov,
          llvm-cxxdump, llvm-diff, llvm-dis, llvm-dsymutil, llvm-dwarfdump,
          llvm-extract, llvm-link, llvm-mc, llvm-mcmarkup, llvm-nm,
          llvm-objdump, llvm-pdbdump, llvm-profdata, llvm-ranlib (symlink),
          llvm-readobj, llvm-rtdyld, llvm-size, llvm-stress, llvm-symbolizer,
          llvm-tblgen, macho-dump, not, obj2yaml, opt, scan-build (symlink),
          scan-view (symlink), verify-uselistorder, and yaml2obj
        </seg>
        <seg>
          BugpointPasses.so, libclang.so, libLLVM-&llvm-version;.so,
          libLTO.so,<!-- libprofile_rt.so,--> LLVMHello.so and numerous
          static libraries in /usr/lib
        </seg>
        <seg>
          /usr/include/{clang,clang-c,llvm,llvm-c},
          /usr/lib/{clang,clang-analyzer}, and
          /usr/share/{doc/llvm-&llvm-version;,llvm}
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="bugpoint">
        <term><command>bugpoint</command></term>
        <listitem>
          <para>
            is the automatic test case reduction tool.
          </para>
          <indexterm zone="llvm bugpoint">
            <primary sortas="b-bugpoint">bugpoint</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="clang">
        <term><command>clang</command></term>
        <listitem>
          <para>
            is the <application>Clang</application> C, C++,
            and Objective-C compiler.
          </para>
          <indexterm zone="llvm clang">
            <primary sortas="b-clang">clang</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llc">
        <term><command>llc</command></term>
        <listitem>
          <para>
            is the <application>LLVM</application> static compiler.
          </para>
          <indexterm zone="llvm llc">
            <primary sortas="b-llc">llc</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lli">
        <term><command>lli</command></term>
        <listitem>
          <para>
            is used to directly execute programs from
            <application>LLVM</application> bitcode.
          </para>
          <indexterm zone="llvm lli">
            <primary sortas="b-lli">lli</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llvm-ar">
        <term><command>llvm-ar</command></term>
        <listitem>
          <para>
            is the <application>LLVM</application> archiver.
          </para>
          <indexterm zone="llvm llvm-ar">
            <primary sortas="b-llvm-ar">llvm-ar</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llvm-as">
        <term><command>llvm-as</command></term>
        <listitem>
          <para>
            is the <application>LLVM</application> assembler.
          </para>
          <indexterm zone="llvm llvm-as">
            <primary sortas="b-llvm-as">llvm-as</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llvm-bcanalyzer">
        <term><command>llvm-bcanalyzer</command></term>
        <listitem>
          <para>
            is the <application>LLVM</application> bitcode analyzer.
          </para>
          <indexterm zone="llvm llvm-bcanalyzer">
            <primary sortas="b-llvm-bcanalyzer">llvm-bcanalyzer</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llvm-config">
        <term><command>llvm-config</command></term>
        <listitem>
          <para>
            Prints <application>LLVM</application> compilation options.
          </para>
          <indexterm zone="llvm llvm-config">
            <primary sortas="b-llvm-config">llvm-config</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llvm-cov">
        <term><command>llvm-cov</command></term>
        <listitem>
          <para>
            is used to emit coverage information.
          </para>
          <indexterm zone="llvm llvm-cov">
            <primary sortas="b-llvm-cov">llvm-cov</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llvm-cxxdump">
        <term><command>llvm-cxxdump</command></term>
        <listitem>
          <para>
            is used for C++ ABI Data Dumper.
          </para>
          <indexterm zone="llvm llvm-cxxdump">
            <primary sortas="b-llvm-cxxdump">llvm-cxxdump</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llvm-diff">
        <term><command>llvm-diff</command></term>
        <listitem>
          <para>
            is the <application>LLVM</application> structural
            '<command>diff</command>'.
          </para>
          <indexterm zone="llvm llvm-diff">
            <primary sortas="b-llvm-diff">llvm-diff</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llvm-dis">
        <term><command>llvm-dis</command></term>
        <listitem>
          <para>
            is the <application>LLVM</application> disassembler.
          </para>
          <indexterm zone="llvm llvm-dis">
            <primary sortas="b-llvm-dis">llvm-dis</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llvm-dsymutil">
        <term><command>llvm-dsymutil</command></term>
        <listitem>
          <para>
            tool used to manipulate archived DWARF debug symbol files,
            compatible with the Darwin command <command>dsymutil</command>.
          </para>
          <indexterm zone="llvm llvm-dsymutil">
            <primary sortas="b-llvm-dsymutil">llvm-dsymutil</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llvm-extract">
        <term><command>llvm-extract</command></term>
        <listitem>
          <para>
            is used to extract a function from an
            <application>LLVM</application> module.
          </para>
          <indexterm zone="llvm llvm-extract">
            <primary sortas="b-llvm-extract">llvm-extract</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llvm-link">
        <term><command>llvm-link</command></term>
        <listitem>
          <para>
            is the <application>LLVM</application> linker.
          </para>
          <indexterm zone="llvm llvm-link">
            <primary sortas="b-llvm-link">llvm-link</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llvm-nm">
        <term><command>llvm-nm</command></term>
        <listitem>
          <para>
            is used to list <application>LLVM</application> bitcode
            and object file's symbol table.
          </para>
          <indexterm zone="llvm llvm-nm">
            <primary sortas="b-llvm-nm">llvm-nm</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llvm-pdbdump">
        <term><command>llvm-pdbdump</command></term>
        <listitem>
          <para>
            is used as PDB Dumper.
          </para>
          <indexterm zone="llvm llvm-pdbdump">
            <primary sortas="b-llvm-pdbdump">llvm-pdbdump</primary>
          </indexterm>
        </listitem>
      </varlistentry>
<!--
      <varlistentry id="llvm-prof">
        <term><command>llvm-prof</command></term>
        <listitem>
          <para>
            is used to print execution profile of
            <application>LLVM</application> program.
          </para>
          <indexterm zone="llvm llvm-prof">
            <primary sortas="b-llvm-prof">llvm-prof</primary>
          </indexterm>
        </listitem>
      </varlistentry>-->

      <varlistentry id="llvm-ranlib">
        <term><command>llvm-ranlib</command></term>
        <listitem>
          <para>
            is used to generate index for <application>LLVM</application>
            archive.
          </para>
          <indexterm zone="llvm llvm-ranlib">
            <primary sortas="b-llvm-ranlib">llvm-ranlib</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llvm-stress">
        <term><command>llvm-stress</command></term>
        <listitem>
          <para>
            is used to generate random
            <filename class="extension">.ll</filename> files.
          </para>
          <indexterm zone="llvm llvm-stress">
            <primary sortas="b-llvm-stress">llvm-stress</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="llvm-tblgen">
        <term><command>llvm-tblgen</command></term>
        <listitem>
          <para>
            is the <application>LLVM</application> Target Description
            To C++ Code Generator.
          </para>
          <indexterm zone="llvm llvm-tblgen">
            <primary sortas="b-llvm-tblgen">llvm-tblgen</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="obj2yaml">
        <term><command>obj2yaml</command></term>
        <listitem>
          <para>
            takes an object file,and produces a YAML representation of the
            file.
          </para>
          <indexterm zone="llvm obj2yaml">
            <primary sortas="b-obj2yaml">obj2yaml</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="opt">
        <term><command>opt</command></term>
        <listitem>
          <para>
            is the <application>LLVM</application> optimizer.
          </para>
          <indexterm zone="llvm opt">
            <primary sortas="b-opt">opt</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="scan-build">
        <term><command>scan-build</command></term>
        <listitem>
          <para>
            is a <application>Perl</application> script that invokes the
            <application>Clang</application> static analyzer.
          </para>
          <indexterm zone="llvm scan-build">
            <primary sortas="b-scan-build">scan-build</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="yaml2obj">
        <term><command>yaml2obj</command></term>
        <listitem>
          <para>
            takes a YAML representation of an object file and converts it
            to an binary file.
          </para>
          <indexterm zone="llvm yaml2obj">
            <primary sortas="b-yaml2obj">yaml2obj</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libllvm">
        <term><filename class="libraryfile">libLLVM-&llvm-version;.so</filename></term>
        <listitem>
          <para>
            contains the <application>LLVM</application> API functions.
          </para>
          <indexterm zone="llvm libllvm">
            <primary sortas="c-libllvm">libLLVM-&llvm-version;.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>
<!--
      <varlistentry id="libprofile_rt">
        <term><filename class="libraryfile">libprofile_rt.so</filename></term>
        <listitem>
          <para>
            is the C, C++ and Objective-C runtime library for
            <application>Clang</application>.
          </para>
          <indexterm zone="llvm libprofile_rt">
            <primary sortas="c-libprofile_rt">libprofile_rt.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>-->

    </variablelist>

  </sect2>

</sect1>