source: general/prog/fpc.xml@ 179da23c

<?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 fpc-bin-x86-dl           "https://mirror.freemirror.org/pub/fpc/dist/&freepascal-bin-version;/x86_64-linux/fpc-&freepascal-bin-version;-x86_64-linux.tar">
  <!ENTITY fpc-bin-x86-md5sum       "519c5e0b9e7b61c07d61511a52aaecaa">
  <!ENTITY fpc-bin-x86-size         "80.4 MB">
  <!ENTITY fpc-bin-x86-bldsize      "x.x MB">
  
  <!ENTITY fpc-bin-i686-dl          "https://mirror.freemirror.org/pub/fpc/dist/&freepascal-bin-version;/i386-linux/fpc-&freepascal-bin-version;.i386-linux.tar">
  <!ENTITY fpc-bin-i686-md5sum      "2d9dece3f2c83a82cb07e422e59ca91e">
  <!ENTITY fpc-bin-i686-size        "146.7 MB">
  <!ENTITY fpc-bin-i686-bldsize     "x.x MB">

  <!ENTITY fpc-src-dl               "https://sourceforge.net/projects/freepascal/files/Source/&freepascal-version;/fpc-&freepascal-version;.source.tar.gz">
  <!ENTITY fpc-src-md5sum           "e7649ad0fc9230fdd9493a7fcabbd426">
  <!ENTITY fpc-src-size             "52.2 MB">
  <!ENTITY fpc-src-bldsize          "x.x MB">
  
  <!ENTITY fpc-tmp-target           "/opt/fpc-temp">
]>

<!--
  TODO:
  
  Rebuild itself
     The instructions below does the bootstrap by using a 
     binary package to compile the compiler.
     I've never tested whether the built compiler is capable
     to recompile itself, maybe it work, maybe not. With the
     compiler which is installed, building QT5PAS and Lazarus
     (the Delphi-like GUI) with QT or GTK2 toolkits does work.

     We definitly should test this and maybe tweak the instructions
     to do a correct build to enable this.
-->

<sect1 id="fpc" xreflabel="FreePascal-&freepascal-version;">
  <?dbhtml filename="fpc.html"?>

  <sect1info>
    <date>$Date$</date>
  </sect1info>

  <title>FreePascal-&freepascal-version;</title>

  <indexterm zone="java">
    <primary sortas="a-java">FreePascal Binary</primary>
  </indexterm>

  <sect2 id="fpc-bin" xreflabel="FPC Binary" role="package">
    <title>Binary FreePascal Information</title>

    <para>
      FreePascal is a compiler software used to translate Pascal
      source code to executable programs. An introductory Pascal
      program looks like:
    </para>

<screen><literal>program Hello;
begin
    writeln('Hello world!');
end.</literal></screen>

    <para>
      The <application>FreePascal</application> package does not only
      contain the compiler itself but also a complete semi-graphical,
      text based IDE. This IDE can be operated using keyboard commands
      and by mouse interaction. The IDE is constructed with a toolkit
      previously named <application>Turbo Vision</application> which
      was introduced by Borland somewhere back in the MS-DOS age
      together with <application>Turbo Pascal 6.0</application>
      - that was in Nov. 1990. This toolbox is available for own
      programs, too.
    </para>

    <para>
      Creating the <application>FreePascal</application> compiler from
      source requires a <application>FreePascal</application> compiler
      to be available. This is a circular dependency which can be
      solved by using a precompiled package.
    </para>

    <para>
      To start, we set up a binary installation of <application>FreePascal</application>
      created by the FreePascal development team. It is installed in
      the <filename>/opt</filename> directory. Using this temporary
      compiler installation, the compiler can be created from source.
      After this step is done, the temporary compiler can be easily
      removed.
    </para>

    &lfs110a_checked;

    <bridgehead renderas="sect3">Binary Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Binary download (x86): <ulink url="&fpc-bin-i686-dl;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &fpc-bin-i686-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size (binary): &fpc-bin-i686-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &fpc-bin-i686-bldsize;
        </para>
      </listitem>
    </itemizedlist>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Binary download (x86_64): <ulink url="&fpc-bin-x86-dl;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &fpc-bin-x86-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size (binary): &fpc-bin-x86-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &fpc-bin-x86-bldsize;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Source Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Source download: <ulink url="&fpc-src-dl;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &fpc-src-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size (binary): &fpc-src-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &fpc-src-bldsize;
        </para>
      </listitem>
    </itemizedlist>
    
    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Optional patch (Required if building on i686 systems):
          <ulink url="&patch-root;/fpc-&freepascal-version;-glibc_2.34-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">FreePascal Dependencies</bridgehead>
    <para role="required">
      <xref linkend="gdb"/> (with static library libgdb.a)
    </para>

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

  </sect2>

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

    <note>
      <para>
        While installation it is required to have administrator
        privileges. It is assumed that the current user is allowed
        to use <command>sudo</command> to gain full privileges.
      </para>
      <para>
        Even a temporary binary compiler must be installed prior to
        compile the compiler from the source, it is assumed that the
        <application>FreePascal</application> sources has been
        extracted and the current directory has been changed to it just
        like as usual.
      </para>
      <para>
        In case there is a <application>FreePascal</application>
        compiler installed allready, the temporary binary is not
        required. The installed compiler should be appropriate to
        compile the sources if the installed version is not too old.
      </para>
    </note>

    <para>
      Begin by extracting the appropriate binary tarball for your
      architecture and changing to the extracted directory. This
      extraction is performed within the extracted source directory.
      Install the binary <application>FreePascal</application> and
      remove some unused files with the following commands:
    </para>

<screen><userinput>case "$(uname -m)" in
    i?86)
        tar -xf ../../fpc-&freepascal-bin-version;.i386-linux.tar &amp;&amp;
        cd fpc-&freepascal-bin-version;.i386-linux
        ;;
    x86_64)
        tar -xf ../../fpc-&freepascal-bin-version;-x86_64-linux.tar &amp;&amp;
        cd fpc-&freepascal-bin-version;-x86_64-linux
        ;;
esac &amp;&amp;
rm demo.tar.gz &amp;&amp;
rm doc-pdf.tar.gz &amp;&amp;
sed -e 's;PREFIX=/usr;test -z "$PREFIX" \&amp;\&amp; &amp;;' -i install.sh</userinput></screen>

    <para>
      Prepare the install directory for the temporary compiler and
      make it writable to the current user by executing as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>install -dm755 -o $(id -u) &fpc-tmp-target;</userinput></screen>

    <para>
      Install the temporary compiler:
    </para>
      
<screen><userinput>yes "" | { PREFIX=&fpc-tmp-target; ./install.sh; }</userinput></screen>

    <para>Remove the extracted binary objects:</para>
    
<screen><userinput>cd .. &amp;&amp;
case "$(uname -m)" in
    i?86)
        rm -rf fpc-&freepascal-bin-version;.i386-linux
        ;;
    x86_64)
        rm -rf fpc-&freepascal-bin-version;-x86_64-linux
        ;;
esac &amp;&amp;
export PATH=&fpc-tmp-target;/bin:$PATH</userinput></screen>

    <para>
      The binary version is now installed in
      <filename class="directory">&fpc-tmp-target;</filename> and
      can be used to create the compiler and utilities from source.
    </para>

    <para>
      Fix invalid path for man pages:
    </para>

<screen><userinput>sed -e "/^INSTALL_MANDIR=/ s;/man;/share/man;" \
    -i install/man/Makefile</userinput></screen>

    <para>
      If building on i686 systems (32-bit), a patch is required
      to overcome an issue with glibc-2.34.
    </para>

<screen><userinput>cd fpcsrc &amp;&amp;
patch -Np1 -i ../../fpc-&freepascal-version;-glibc_2.34-2.patch &amp;&amp;
cd ..</userinput></screen>

    <para>
      Compile the <application>FreePascal</application> compiler
      and tools by executing the following commands:
    </para>

<screen><userinput>make clean &amp;&amp;
make  build</userinput></screen>
    
    <para>
      Install the <application>FreePascal</application> compiler
      and tools by executing the following commands as the
      <systemitem class="username">root</systemitem> user. Make sure
      that the temporary compiler is in <envar>PATH</envar>:
    </para>

<screen role="root"><userinput>make -j1 PREFIX=/usr install &amp;&amp;
case "$(uname -m)" in
    i?86)
        ln -svf /usr/lib/fpc/&freepascal-version;/ppc386 /usr/bin/
        ;;
    x86_64)
        ln -svf /usr/lib/fpc/&freepascal-version;/ppcx64 /usr/bin/
        ;;
esac</userinput></screen>

    <para>
      Now that the compiler has been created from source, the temporary
      compiler in <filename class="directory">&fpc-tmp-target;</filename>
      can be removed. Execute the following commands as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>rm -rf /etc/fppkg* &amp;&amp;
rm -rf /etc/fpc.* &amp;&amp;
rm -rf $HOME/{.fppkg,.fpc.cfg,.config/fppkg.cfg} &amp;&amp;
rm -rf &fpc-tmp-target;</userinput></screen>

    <para>
      You may also want to remove the <filename class="directory">&fpc-tmp-target;</filename>
      entry from <envar>PATH</envar> now.
    </para>
  </sect2>

  <sect2 role="configuration">
    <title>Configuring FreePascal</title>

    <para>
      A default configuration file <filename>/etc/fpc.cfg</filename>
      can be created by a tool which is part of the compiler suite.
      Generate the default config file as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>/usr/lib/fpc/&freepascal-version;/samplecfg /usr/lib/fpc/&freepascal-version; /etc &amp;&amp;
cat &gt;&gt; /etc/fpc.cfg &lt;&lt;EOF
#ifdef cpux86_64
# for x86_64 use -fPIC by default
-Cg
#endif
EOF</userinput></screen>

    <para>
      If you are going to use QT (most likely when building Lazarus
      with the QT library), add the QT library path to the config as the
      <systemitem class="username">root</systemitem> user:
    </para>
    
<screen role="root"><userinput>sed -e "/^-Fl\/usr\/lib\/fpc/a -Fl/opt/qt5/lib" \
    -i /etc/fpc.cfg</userinput></screen>

    <para>
      It is highly recommended that the compiler sources are available
      for later use. Since the sources are available on disk already
      they can be used but some binaries built in the source tree
      should be removed first:
    </para>

<screen><userinput>make clean</userinput></screen>

    <para>
      To copy the source, execute the following command as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>mv fpcsrc /usr/lib/fpc/src</userinput></screen>

  </sect2>

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

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

      <seglistitem>
        <seg>fpc, fp, samplecfg, ...</seg>
        <seg>None</seg>
        <seg>/usr/lib/fpc</seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="i-fp">
        <term><command>fp</command></term>
        <listitem>
          <para>
            FreePascal text based IDE
          </para>
          <indexterm zone="fpc i-fp">
            <primary sortas="b-fp">fp</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="i-fpc">
        <term><command>fpc</command></term>
        <listitem>
          <para>
            FreePascal compiler frontend
          </para>
          <indexterm zone="fpc i-fpc">
            <primary sortas="b-fpc">fpc</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="i-fpcmake">
        <term><command>fpcmake</command></term>
        <listitem>
          <para>
            FreePascal make utility
          </para>
          <indexterm zone="fpc i-fpcmake">
            <primary sortas="b-fpcmake">fpcmake</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="i-samplecfg">
        <term><command>samplecfg</command></term>
        <listitem>
          <para>
            Utility to create a default configuration file
          </para>
          <indexterm zone="fpc i-samplecfg">
            <primary sortas="b-samplecfg">samplecfg</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>