PERFORCE change 170633 for review

[Rene Ladan]

http://p4web.freebsd.org/chv.cgi?CH=170633

Change 170633 by rene at rene_self on 2009/11/14 23:32:57

	[porters handbook]
	Add a section about Clang to the "Dos and Don'ts" chapter.
	To be reviewed by the clang team and the doc review team.

Affected files ...

.. //depot/projects/docproj_nl/en_US.ISO8859-1/books/porters-handbook/book.sgml#50 edit

Differences ...

==== //depot/projects/docproj_nl/en_US.ISO8859-1/books/porters-handbook/book.sgml#50 (text+ko) ====

@@ -13602,6 +13602,92 @@
 	  shorthand solution.</para>
       </sect1>
 
+      <sect1 id="dads-clang">
+	<title>Clang: new C/C++ compiler</title>
+
+	<para>A future version of &os; will likely have the Clang C/C++
+	  compiler as its base compiler.  Some modifications to the Ports
+	  Collection are necessary.  In general, these are <quote>write proper
+	    ports</quote> and <quote>write proper source code</quote>.  More
+	  specifically:</para>
+
+	<itemizedlist>
+	  <listitem>
+	    <para>Respect <makevar>CC</makevar> and <makevar>CXX</makevar>. Do
+	      not any of <filename>cc</filename>, <filename>c99</filename>,
+	      <filename>gcc</filename>, <filename>c++</filename>, or
+	      <filename>g++</filename> directly.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Respect <makevar>LD</makevar>, do not use
+	      <filename>ld</filename> directly.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Do not use <filename>cpp</filename> for reformatting manual
+	      pages or shell scripts.  Try to use something more suitable
+	      instead, possibly falling back to <makevar>CPP</makevar>.</para>
+	      <!-- (rene) what about the C++ preprocessor? -->
+	  </listitem>
+
+	  <listitem>
+	    <para>If there are link errors related to missing or already
+	      defined functions, try to add <makevar>CSTD=gnu89</makevar> to
+	      <filename>Makefile</filename>.  The function vsnprintf() is
+	      already built in.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>The <literal>-traditional</literal> option is not supported,
+	      so existing occurences have to be removed.  No concensus has yet
+	      been reached on ports abusing this option to preserve white space
+	      in text formatting.  Note that the Clang preprocessor does not
+	      preserve white space.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Explicit type indication of variables must be used in
+	      built-in assembler code.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>The main function must be properly declared as</para>
+
+	    <programlisting>int main(int argc, char **argv)</programlisting>
+	  </listitem>
+
+	  <listitem>
+	    <para>The maximum useable optimization level is 3.  Level 4 is
+	      reserved for link-time optimization for the Clang backend.</para>
+	  </listitem>
+
+	  <!--(rene) -I and -L belong to CONFIGURE_ENV, not to CFLAGS (?)-->
+	</itemizedlist>
+
+	<para>Some temporary hacks that might be used if all else fails:</para>
+
+	<itemizedlist>
+	  <listitem>
+	    <para>Adding <literal>-fheinous-gnu-extensions</literal>.  Note
+	      that this option is already deprecated.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Reducing the warning level by adding
+	      <literal>--diasable-werror</literal> or
+	      <literal>--disable-strict</literal>, or by disabling
+	      <literal>--warn-common</literal> or
+	      <literal>-Werror</literal>.</para>
+	  </listitem>
+	</itemizedlist>
+
+<!--
+	<para>A current set of patches are available at <ulink
+	  url="http://www.rainbow-runner.nl/clang/patches">this patch site</ulink>.</para>
+-->
+      </sect1>
+
       <sect1 id="dads-cc">
 	<title>Respect both <makevar>CC</makevar> and
 	  <makevar>CXX</makevar></title>