Re: FAQ_Solaris 1.28 to spanish

Peter Eisentraut wrote:
>> I have new things to add, specially for Open Solaris plattaform
>> specifications. I can write a new FAQ or just concatenate to this the other
>> features of OSolaris?
>
> In my opinion, the platform FAQs should be scrapped and the information should
> be placed into the real documentation at the appropriate places.

Here is a beginning patch of what I am planning to do with the platform
FAQs in terms of getting it integrated into the main documentation.  If
you don't like where this is going, please speak up.
Index: doc/src/sgml/installation.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v
retrieving revision 1.313
diff -u -3 -p -r1.313 installation.sgml
--- doc/src/sgml/installation.sgml    5 Sep 2008 12:11:18 -0000    1.313
+++ doc/src/sgml/installation.sgml    18 Nov 2008 10:18:03 -0000
@@ -2001,8 +2001,9 @@ kill `cat /usr/local/pgsql/data/postmast
    FreeBSD, OpenBSD, NetBSD, Mac OS X, AIX, HP/UX, IRIX, Solaris, Tru64 Unix,
    and UnixWare.  Other Unix-like systems may also work but are not currently
    being tested.  In most cases, all CPU architectures supported by
-   a given operating system will work.  Look in the <filename>doc/</>
-   directory of the source distribution to see if there is a FAQ document
+   a given operating system will work.  Look in
+   the <xref linkend="installation-platform-notes"> below to see if
+   there is information
    specific to your operating system, particularly if using an older system.
   </para>

@@ -2011,9 +2012,202 @@ kill `cat /usr/local/pgsql/data/postmast
    to be supported according to recent build farm results, please report
    it to <email>pgsql-bugs@postgresql.org</email>.  If you are interested
    in porting <productname>PostgreSQL</> to a new platform,
-   <email>pgsql-ports@postgresql.org</email> is the appropriate place
+   <email>pgsql-hackers@postgresql.org</email> is the appropriate place
    to discuss that.
   </para>
  </sect1>

+ <sect1 id="installation-platform-notes">
+  <title>Platform-Specific Notes</title>
+
+  <sect2 id="installation-notes-solaris">
+   <title>Solaris</title>
+
+   <sect3>
+    <title>Required tools</title>
+
+    <para>
+     To build and install PostgreSQL on Solaris, you will need
+     <itemizedlist>
+      <listitem><para>gzip (for installing the documentation)</para></listitem>
+      <listitem><para>GNU Make</para></listitem>
+      <listitem><para>GNU Readline library (optional)</para></listitem>
+      <listitem><para>Sun Studio CC or GCC</para></listitem>
+     </itemizedlist>
+
+     You can download Sun Studio
+     from <ulink url="http://developers.sun.com/sunstudio/downloads/"></ulink>.
+     Many of GNU tools are integrated into Solaris 10, or they are
+     present on the Solaris companion CD.  If you like packages for
+     older version of Solaris, you can find these tools
+     at <ulink url="http://www.sunfreeware.com"></ulink>
+     or <ulink url="http://www.blastwave.org"></ulink>.  If you prefer
+     sources, look
+     at <ulink url="http://www.gnu.org/order/ftp.html"></ulink>.
+    </para>
+
+    <para>
+     You can build with either GCC or Sun's compiler suite.  For
+     better code optimization, Sun's compiler is strongly recommended
+     on the SPARC architecture.  We have heard reports of problems
+     when using GCC 2.95.1; gcc 2.95.3 or later is recommended.  If
+     you are using Sun's compiler, be careful not to select
+     <filename>/usr/ucb/cc</filename>;
+     use <filename>/opt/SUNWspro/bin/cc</filename>.
+    </para>
+   </sect3>
+
+   <sect3>
+    <title>Problems with OpenSSL</title>
+
+    <para>
+     When you build PostgreSQL with OpenSSL support you might get
+     compilation errors in the following files:
+     <itemizedlist>
+      <listitem><para><filename>src/backend/libpq/crypt.c</filename></para></listitem>
+      <listitem><para><filename>src/backend/libpq/password.c</filename></para></listitem>
+      <listitem><para><filename>src/interfaces/libpq/fe-auth.c</filename></para></listitem>
+      <listitem><para><filename>src/interfaces/libpq/fe-connect.c</filename></para></listitem>
+     </itemizedlist>
+
+     This is because of a namespace conflict between the standard
+     <filename>/usr/include/crypt.h</filename> header and the header
+     files provided by OpenSSL.
+    </para>
+
+    <para>
+     Upgrading your OpenSSL installation to version 0.9.6a fixes this
+     problem.  Solaris 9 and above has a newer version of OpenSSL.
+    </para>
+   </sect3>
+
+   <sect3>
+    <title>configure complains about a failed test program</title>
+
+    <para>
+     If configure complains about a failed test program, this is
+     probably a case of the run-time linker being unable to find some
+     library, probably libz, libreadline or some other non-standard
+     library such as libssl.  To point it to the right location, set
+     the <envar>LDFLAGS</envar> environment variable, e.g.,
+<programlisting>
+LDFLAGS="-R /usr/sfw/lib:/opt/sfw/lib:/usr/local/lib"
+export LDFLAGS
+</programlisting>
+     and restart configure.  See
+     the <citerefentry><refentrytitle>ld</><manvolnum>1</></citerefentry>
+     man page for more information.
+    </para>
+   </sect3>
+
+   <sect3>
+    <title>64-bit build sometimes crashes</title>
+
+    <para>
+     On Solaris 7 and older, the 64-bit version of libc has a buggy
+     <function>vsnprintf</function> routine, which leads to erratic
+     core dumps in PostgreSQL.  The simplest known workaround is to
+     force PostgreSQL to use its own version of vsnprintf rather than
+     the library copy.  To do this, after you
+     run <command>configure</command> edit a file produced by
+     <command>configure</command>:
+     In <filename>src/Makefile.global</filename>, change the line
+<programlisting>
+LIBOBJS =
+</programlisting>
+     to read
+<programlisting>
+LIBOBJS = snprintf.o
+</programlisting>
+     (There might be other files already listed in this variable.
+     Order does not matter.)  Then build as usual.
+    </para>
+   </sect3>
+
+   <sect3>
+    <title>Compiling for optimal performance</title>
+
+    <para>
+     On the SPARC architecture, Sun Studio is strongly recommended for
+     compilation.  Try using the <option>-xO5</option> optimization
+     flag to generate significantly faster binaries.  Do not use any
+     flags that modify behavior of floating-point operations
+     and <varname>errno</varname> processing (e.g.,
+     <option>-fast</option>).  These flags could raise some
+     nonstandard PostgreSQL behavior for example in the date/time
+     computing.
+    </para>
+
+    <para>
+     If you do not have a reason to use 64-bit binaries on SPARC,
+     prefer the 32-bit version.  The 64-bit operations are slower and
+     64-bit binaries are slower than the 32-bit variants.  And on
+     other hand, 32-bit code on the AMD64 CPU family is not native,
+     and that is why 32-bit code is significant slower on this CPU
+     family.
+    </para>
+   </sect3>
+
+   <sect3>
+    <title>Solaris packages</title>
+
+    <para>
+     PostgreSQL is bundled with Solaris 10 (from update 2).  Official
+     packages are also available on
+     <ulink url="http://pgfoundry.org/projects/solarispackages/"></ulink>.
+     Packages for older Solaris versions (8, 9) you can be obtained
+     from <ulink url="http://www.sunfreeware.com/"></ulink> or
+     <ulink url="http://www.blastwave.org/"></ulink>.
+    </para>
+   </sect3>
+
+   <sect3>
+    <title>Performance tuning</title>
+
+    <para>
+     Some tricks for tuning PostgreSQL and Solaris for performance can
+     be found
+     at <ulink url="http://www.sun.com/servers/coolthreads/tnb/applications_postgresql.jsp"></ulink>.
+     This article is primary focused on T2000 platform, but many of
+     the recommendations are also useful on other hardware with
+     Solaris.
+    </para>
+   </sect3>
+
+   <sect3>
+    <title>Using DTrace for tracing PostgreSQL</title>
+
+    <para>
+     Yes, using DTrace is possible.  See <xref linkend="monitoring">
+     for further information.  You can also find more information in
+     this
+     article: <ulink url="http://blogs.sun.com/robertlor/entry/user_level_dtrace_probes_in"></ulink>.
+    </para>
+
+    <para>
+     If you see the linking of the postgres executable abort with an
+     error message like
+<screen>
+Undefined                       first referenced
+ symbol                             in file
+AbortTransaction                    utils/probes.o
+CommitTransaction                   utils/probes.o
+ld: fatal: Symbol referencing errors. No output written to postgres
+collect2: ld returned 1 exit status
+gmake: *** [postgres] Error 1
+</screen>
+     your DTrace installation is too old to handle probes in static
+     functions.  You need Solaris 10u4 or newer.  A workaround is to
+     remove the
+     <literal>static</literal> key word from the function declarations
+     of <function>AbortTransaction</function>
+     and <function>CommitTransaction</function>
+     in <filename>src/backend/access/transam/xact.c</filename>.  See
+     also <ulink url="http://sunsolve.sun.com/search/document.do?assetkey=1-1-2139224-1"></ulink>
+     (registration required).
+    </para>
+   </sect3>
+  </sect2>
+ </sect1>
+
 </chapter>