cvs.sgml

PostgreSQL7.4.6 for Linux

#
# Defaults that apply to all the collections
*default host=cvsup.postgresql.org
*default compress
*default release=cvs
*default delete use-rel-suffix
*default tag=.

# base directory where CVSup will store its 'bookmarks' file(s)
*default base=<replaceable class="parameter">/usr/local/pgsql</replaceable>

# prefix directory where CVSup will store the actual distribution(s)
*default prefix=<replaceable class="parameter">/usr/local/pgsql</replaceable>

# complete distribution, including all below
pgsql

# individual distributions vs 'the whole thing'
# pgsql-doc
# pgsql-perl5
# pgsql-src

    </programlisting>
   </para>
  </sect2>

  <sect2>
   <title>Installing <productname>CVSup</productname></title>

   <para>
    <productname>CVSup</productname> is available as source, pre-built
    binaries, or Linux RPMs. It is far easier to use a binary than to
    build from source, primarily because the very capable, but
    voluminous, Modula-3 compiler is required for the build.
   </para>

   <procedure>
    <title><productname>CVSup</productname> Installation from Binaries</title>

    <para>
     You can use pre-built binaries
     if you have a platform for which binaries
     are posted on
     <ulink url="ftp://ftp.postgresql.org/pub">the <productname>PostgreSQL</productname> ftp site</ulink>,
     or if you are running FreeBSD, for which
     <productname>CVSup</productname> is available as a port.

     <note>
      <para>
       <productname>CVSup</productname> was originally developed as a
       tool for distributing the <productname>FreeBSD</productname>
       source tree. It is available as a <quote>port</quote>, and for those running
       FreeBSD, if this is not sufficient to tell how to obtain and
       install it then please contribute a procedure here.
      </para>
     </note>
    </para>

    <para>
     At the time of writing, binaries are available for
     Alpha/Tru64, ix86/xBSD,
     HPPA/HP-UX 10.20, MIPS/IRIX,
     ix86/linux-libc5, ix86/linux-glibc,
     Sparc/Solaris, and Sparc/SunOS.
    </para>

    <step>
     <para>
      Retrieve the binary tar file for
      <application>cvsup</application>
      (<application>cvsupd</application> is not required
      to be a client) appropriate for your platform.
     </para>

     <substeps>
      <step performance="optional">
       <para>
	If you are running FreeBSD, install the <productname>CVSup</productname> port.
       </para>
      </step>

      <step performance="optional">
       <para>
	If you have another platform, check for and download the appropriate binary from
	<ulink url="ftp://ftp.postgresql.org/pub">the <productname>PostgreSQL</productname> ftp site</ulink>.
       </para>
      </step>
     </substeps>
    </step>

    <step>
     <para>
      Check the tar file to verify the contents and directory
      structure, if any. For the linux tar file at least, the static binary
      and man page is included without any directory packaging.
     </para>

     <substeps>
      <step>
       <para>
	If the binary is in the top level of the tar file, then simply
	unpack the tar file into your target directory:

	<programlisting>
$ cd /usr/local/bin
$ tar zxvf /usr/local/src/cvsup-16.0-linux-i386.tar.gz
$ mv cvsup.1 ../doc/man/man1/
	</programlisting>
       </para>
      </step>

      <step>
       <para>
	If there is a directory structure in the tar file, then unpack
	the tar file within /usr/local/src and move the binaries into
	the appropriate location as above.
       </para>
      </step>
     </substeps>
    </step>

    <step>
     <para>
      Ensure that the new binaries are in your path.

      <programlisting>
$ rehash
$ which cvsup
$ set path=(<replaceable>path to cvsup</replaceable> $path)
$ which cvsup
/usr/local/bin/cvsup
      </programlisting>
     </para>
    </step>
   </procedure>
  </sect2>

  <sect2>
   <title>Installation from Sources</title>

   <para>
    Installing <productname>CVSup</productname> from sources is not
    entirely trivial, primarily because most systems will need to
    install a Modula-3 compiler first.
    This compiler is available as Linux <productname>RPM</productname>,
    FreeBSD package, or source code.

    <note>
     <para>
      A clean-source installation of Modula-3 takes roughly 200MB of disk space,
      which shrinks to roughly 50MB of space when the sources are removed.</para>
    </note>
   </para>

   <procedure>
    <title>Linux installation</title>

    <step>
     <para>
      Install Modula-3.
     </para>

     <substeps>
      <step>
       <para>
	Pick up the <productname>Modula-3</productname>
	distribution from
	<ulink url="http://m3.polymtl.ca/m3">Polytechnique Montr閍l</ulink>,
	who are actively maintaining the code base originally developed by
	<ulink
	 url="http://www.research.digital.com/SRC/modula-3/html/home.html">the DEC Systems Research Center</ulink>.
       The <productname>PM3</productname> <productname>RPM</productname> distribution is roughly
	30MB compressed. At the time of writing, the 1.1.10-1 release
	installed cleanly on RH-5.2, whereas the 1.1.11-1 release is
	apparently built for another release (RH-6.0?) and does not run on RH-5.2.

	<tip>
	 <para>
	  This particular rpm packaging has
	  <emphasis>many</emphasis> <productname>RPM</productname> files,
	  so you will likely want to place them into a separate
	  directory.
	 </para>
	</tip>
       </para>
      </step>

      <step>
       <para>
	Install the Modula-3 rpms:

	<programlisting>
# rpm -Uvh pm3*.rpm
	</programlisting>
       </para>
      </step>
     </substeps>
    </step>

    <step>
     <para>
     Unpack the cvsup distribution:

      <programlisting>
# cd /usr/local/src
# tar zxf cvsup-16.0.tar.gz
      </programlisting>
     </para>
    </step>

    <step>
     <para>
      Build the cvsup distribution, suppressing the GUI interface
      feature to avoid requiring X11 libraries:

      <programlisting>
# make M3FLAGS="-DNOGUI"
      </programlisting>

      and if you want to build a static binary to move to systems
      that may not have Modula-3 installed, try:

      <programlisting>
# make M3FLAGS="-DNOGUI -DSTATIC"
      </programlisting>
     </para>
    </step>

    <step>
     <para>
      Install the built binary:

      <programlisting>
# make M3FLAGS="-DNOGUI -DSTATIC" install
      </programlisting>
     </para>
    </step>
   </procedure>
  </sect2>
 </sect1>
</appendix>

<!--
> It became clear that I had a problem with my m3 installation; some
> X11 libraries were not being found correctly.

By the way, you can build the client without the GUI by doing this
in the "client" subdirectory:

    m3build -DNOGUI

If you build it that way, then it doesn't need the X11 libraries and
it's quite a bit smaller.  The GUI is fun to watch, but it's not
very useful.  I originally implemented it because it made debugging
the multi-threaded client program much easier.

To build a statically-linked client, edit <filename>client/src/m3makefile</filename>
to add <literal>build_standalone()</literal>
 just before the <literal>program()</literal> entry near
the end of the file:

<programlisting>
build_standalone()
program(cvsup)
</programlisting>

Then, if cvsup has already been built, remove the machine-specific build directory
(e.g. <filename>LINUXELF/</filename>) and rebuild:

<programlisting>
rm -rf LINUXELF
m3build -DNOGUI -v
cp -p LINUXELF/cvsup /usr/local/bin
</programlisting>

> Anyway, with the reinstall and the two-line patch above (and that
> one include-file _POSIX_SOURCE workaround from the previous try),
> things built cleanly.

Good!

> Now I just need a server somewhere to test.

If you want to try it out, there are public servers for the FreeBSD
source repository at cvsup.freebsd.org and cvsup2.freebsd.org.
Here's a suggested supfile:

*default host=cvsup.freebsd.org compress
*default release=cvs
*default base=/home/jdp/cvsup-test	# FIX THIS
*default delete use-rel-suffix
# *default tag=.
src-bin

This will fetch you the source repository for the programs that get
installed into "/bin".  I chose it because it's one of the smaller
pieces of the system.  Make an empty directory someplace for
testing, and change the "FIX THIS" line to specify that directory
after the "base=".

If you are on a T1 or better, you should probably delete the
"compress" keyword in the first line.

As shown, it will get the repository (RCS) files.  If you uncomment
the line containing "tag=." then it will instead check out the
latest version of each file.  There's a bunch more information about
what you can do in
<ulink url="http://www.freebsd.org/handbook/cvsup.html">the CVSup Handbook</ulink>.

There is one other thing I want to send you, but not tonight.  I
discovered the hard way that you need a malloc package that is
thread-safe with respect to the Modula-3 threads package.  The
Modula-3 runtime takes care to do the proper mutual exclusion around
all calls it makes to malloc.  But if you call certain functions in
the native C library which in turn call malloc, then the mutual
exclusion gets bypassed.  This can lead to rare but baffling core
dumps.

For FreeBSD, I solved this by adding a thread-safe malloc package
into the Modula-3 runtime.  The package is quite portable, and I'm
sure it will work well for Linux with very few changes (probably
none at all).  I want to send it to you along with instructions
for making it a part of the "libm3core" library.  It's very simple,
but I've run out of steam for tonight. :-)  Once you have this
malloc in place, the CVSup system should be rock solid.  We have
servers that have been up for weeks and have served many thousands
of clients without any observed problems.

> We hope to have the PostgreSQL tree using CVSup within a month or
> so, and hope to retire sup in September...

Great!  I'll do my best to help make sure you don't regret it.

John

Tom,

I'm appending the sources for the thread safe version of malloc that
I told you about.  I believe that it will simply compile and work
under Linux, but I've never had an opportunity to test it there.
I urge you to put it into your Modula-3 system; otherwise, you
are guaranteed to get occasional mysterious core dumps from cvsupd.

As a first step, I'd suggest simply trying to compile it under
Linux, like this:

    cc -O -c malloc.c

You shouldn't get any errors or warnings.  If you do, contact me
before you waste any more time on it.

Assuming it compiles OK, copy malloc.c into this directory of your
Modula-3 source tree:

    m3/m3core/src/runtime/LINUXELF

In that same directory, edit "m3makefile" and add this line to the
end of the file:

    c_source       ("malloc")

Then chdir up into "m3/m3core" of the Modula-3 tree and type
"m3build".  (I'm assuming you already have a working Modula-3
installation.)  After that finishes, become root and type "m3ship"
to install it.

That's all there is to it.  If you built cvsup and cvsupd to use
shared libraries, you don't even need to re-link them.  They'll pick
up the change automatically from the updated shared library.

Let me know if you run into any problems with it.

By the way, this is a very good malloc in its own right.  It's worth
using even aside from the thread safety of it.

Regards,
John

I've deposited a statically built cvsup client executable (and man pages
and test configuration) in

  /pub/incoming/cvsup-15.1-client-linux.tar.gz

This was built and linked on Linux/v2.0.30, RH/v4.2, gnulib/v5.3.12 and
includes the thread-safe malloc provided by John Polstra. I'll forward
to you the malloc code and an additional installation e-mail from John.

The Modula-3 installation takes a good bit of room (~50MB?) and the
build environment is unique to Modula-3, but suprisingly enough it
pretty much works.

The cvsup Makefiles do not work on my machine (they are not portable
yet) but each major package (there are 4) can be built without needing
the makefiles with two commands each. Not difficult at all. John gives
some hints in his e-mail on how to build a static executable, and on how
to shrink the size of the executable by leaving out the GUI support.
Again, easy to do.

My client test case, picking up a sub-tree of the FreeBSD distribution,
worked flawlessly. I haven't tried running a server.

Thanks to John for getting me going.

			- Tom


For the thread-safe malloc, do the following:
1) install Modula-3
2) add the enclosed file "malloc.c" to m3/m3core/src/runtime/LINUXELF
3) edit the last line of m3makefile in the same directory to add
     c_source       ("malloc")
4) do an "m3build" and an m3ship from the appropriate directory.

From what John said, the malloc problem can be noticable for the
server-side running cvsupd. Clients may not need it.

Unfortunately I seem to have lost John's original good instructions for
this, so am doing this from memory. May need to ask John to give
instructions again...

			- Tom

-->


<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->