source: general/prog/ruby.xml@ 33cbf497

<?xml version="1.0" encoding="UTF-8"?>
<!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 ruby-download-http "https://cache.ruby-lang.org/pub/ruby/&ruby-minor-version;/ruby-&ruby-version;.tar.xz">
  <!ENTITY ruby-download-ftp  " ">
  <!ENTITY ruby-md5sum        "ce32c274461cc3b8b689d43a9f393c3b">
  <!ENTITY ruby-size          "16 MB">
  <!ENTITY ruby-buildsize     "1.4 GB (with C API docs and tests)">
  <!ENTITY ruby-time          "2.4 SBU (using parallelism=4; with C API docs; add 0.4 SBU for tests)">
]>

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


  <title>Ruby-&ruby-version;</title>

  <indexterm zone="ruby">
    <primary sortas="a-Ruby">Ruby</primary>
  </indexterm>

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

    <para>
      The <application>Ruby</application> package contains the
      <application>Ruby</application> development environment. This
      is useful for object-oriented scripting.
    </para>

    &lfs121_checked;

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

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

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="libyaml"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="doxygen"/>,
      <xref linkend="graphviz"/>,
      <xref linkend="rust"/>,
      <xref linkend="tk"/>,
      <xref linkend="valgrind"/>, 
      &berkeley-db; and 
      <ulink url="https://dtrace.org/about/">DTrace</ulink>
    </para>

    &test-use-internet;

  </sect2>

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

    <para>
      Install <application>Ruby</application> by running the following
      command:
    </para>

<screen><userinput>./configure --prefix=/usr         \
            --disable-rpath       \
            --enable-shared       \
            --without-valgrind    \
            --without-baseruby    \
            ac_cv_func_qsort_r=no \
            --docdir=/usr/share/doc/ruby-&ruby-version; &amp;&amp;
make</userinput></screen>

    <para>
      Optionally, build the CAPI documents by running the following
      commands:
    </para>

<screen><userinput>make capi</userinput></screen>

    <para>
      To test the results, issue: <command>make -j1 -k check</command>.
      Note that running the test suite with parallel jobs may cause test
      failure output as cryptic <computeroutput>unknown
      object</computeroutput> messages, resulting a summary falsely claiming
      <quote>all tests passed</quote>.  If the environment has variables
      related to proxy settings (<envar>all_proxy</envar>,
      <envar>ALL_PROXY</envar>, <envar>http_proxy</envar>, and etc.) set,
      the test suite will bail out early with messages like
      <computeroutput>net/ftp is not found</computeroutput>. Make sure that you
      unset these variables for the test suite. There are over 26,000 tests.
      <!-- https://bugs.ruby-lang.org/issues/20106 -->
      12 tests are known to fail because of expired certificates in the
      test data.
      <!-- https://github.com/ruby/ruby/pull/10616
           https://github.com/ruby/ruby/commit/dd5e625d7bcb -->
      Three tests named
      <literal>TestNetHTTPS#test_session_reuse_but_expire</literal>,
      <literal>OpenSSL::TestASN1#test_utctime</literal>, and
      <literal>OpenSSL::TestASN1#test_generalizedtime</literal> are known
      to fail with OpenSSL-3.3.0 or later.
      Some tests related to ipv6 may indicate errors.  If the
      tests are run in a directory that has a world writable component (e.g.
      /tmp) then several additional tests may fail.
    </para>

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

<screen role="root"><userinput>make install</userinput></screen>

    <note>
      <para>
        If you have Ruby-On-Rails applications installed and did an
        upgrade of <application>Ruby</application> by installing this
        package, you might need to run an update there, too
        (as the &root; user):
      </para>

<screen role="nodump"><userinput>cd /path/to/web/app
bundle update rake</userinput></screen>

      <para>
        and restart the webserver which serves the application.
      </para>

    </note>

  </sect2>

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

    <para>
      <parameter>--disable-rpath</parameter>: This switch disables embedding
      <filename class='directory'>/usr/lib</filename> as a library search
      path into the <command>ruby</command> program.  Doing so is not needed
      (because <filename class='directory'>/usr/lib</filename> is a system
      library path) and it may cause the test suite running with the system
      <filename class='libraryfile'>libruby.so</filename> instead of the
      just built one when Ruby has been installed.
    </para>

    <para>
      <parameter>--enable-shared</parameter>: This switch enables building
      the <filename class="libraryfile">libruby</filename> shared library.
    </para>

    <para>
      <parameter>--without-baseruby</parameter>: This switch prevents using the
      system <command>ruby</command> if it is already installed. The build
      system will use the newly built version instead.
    </para>

    <para>
      <parameter>ac_cv_func_qsort_r=no</parameter>: This switch prevents
      using the <function>qsort_r</function> function from Glibc.  Ruby
      makes some aggressive optimization assuming some implementation
      details of the sorting algorithm, but the assumption is not true with
      the Glibc implementation.  With this switch Ruby will use its own sort
      implementation instead.
    </para>

    <para>
      <option>--disable-install-doc</option>: This switch disables building and
      installing rdoc indexes and C API documents.
    </para>

    <para>
      <option>--disable-install-rdoc</option>: This switch disables building
      and installing rdoc indexes.
    </para>

    <para>
      <option>--disable-install-capi</option>: This switch disables building
      and installing C API documents.
    </para>

  </sect2>

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

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

      <seglistitem>
        <seg>
          bundle,
          bundler,
          erb,
          gem,
          irb,
          racc,
          rake,
          rbs,
          rdbg,
          rdoc,
          ri,
          ruby, and
          typeprof
        </seg>
        <seg>
          libruby.so
        </seg>
        <seg>
          /usr/include/ruby-&ruby-minor-version;.0,
          /usr/lib/ruby,
          /usr/share/doc/ruby-&ruby-version; and
          /usr/share/ri
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="bundle">
        <term><command>bundle</command></term>
        <listitem>
          <para>
            creates bundles of Ruby Gems
          </para>
          <indexterm zone="ruby bundle">
            <primary sortas="b-bundle">bundle</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="bundler">
        <term><command>bundler</command></term>
        <listitem>
          <para>
            manages an application's dependencies throughout it's lifecycle
          </para>
          <indexterm zone="ruby bundler">
            <primary sortas="b-bundler">bundler</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="erb">
        <term><command>erb</command></term>
        <listitem>
          <para>
            is a command line front-end for eRuby, which provides a templating
            system for <application>Ruby</application>
          </para>
          <indexterm zone="ruby erb">
            <primary sortas="b-erb">erb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gem">
        <term><command>gem</command></term>
        <listitem>
          <para>
            is the command for RubyGems, which is a sophisticated package
            manager for <application>Ruby</application>. This is similar
            to Python's 'pip' command
          </para>
          <indexterm zone="ruby gem">
            <primary sortas="b-gem">gem</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="irb">
        <term><command>irb</command></term>
        <listitem>
          <para>
            is the interactive interface for
            <application>Ruby</application>
          </para>
          <indexterm zone="ruby irb">
            <primary sortas="b-irb">irb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rake">
        <term><command>rake</command></term>
        <listitem>
          <para>
            is a make-like build utility for <application>Ruby</application>
          </para>
          <indexterm zone="ruby rake">
            <primary sortas="b-rake">rake</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rdbg">
        <term><command>rdbg</command></term>
        <listitem>
          <para>
            is an interactive debugger for <application>Ruby</application>
          </para>
          <indexterm zone="ruby rdbg">
            <primary sortas="b-rdbg">rdbg</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rdoc">
        <term><command>rdoc</command></term>
        <listitem>
          <para>
            generates <application>Ruby</application> documentation
          </para>
          <indexterm zone="ruby rdoc">
            <primary sortas="b-rdoc">rdoc</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ri">
        <term><command>ri</command></term>
        <listitem>
          <para>
            displays documentation from a database on
            <application>Ruby</application> classes, modules, and methods
          </para>
          <indexterm zone="ruby ri">
            <primary sortas="b-ri">ri</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ruby-prog">
        <term><command>ruby</command></term>
        <listitem>
          <para>
            is an interpreted scripting language for quick
            and easy object-oriented programming
          </para>
          <indexterm zone="ruby ruby-prog">
            <primary sortas="b-ruby">ruby</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libruby">
        <term><filename role="libraryfile">libruby.so</filename></term>
        <listitem>
          <para>
            contains the API functions required by <application>Ruby</application>
          </para>
          <indexterm zone="ruby libruby">
            <primary sortas="c-libruby">libruby.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>