PERFORCE change 170633 for review

[Remko Lodder]

On Nov 15, 2009, at 12:33 AM, Rene Ladan wrote:

> 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
              ^^^ You should probably add something like 'variables' on the end of the line.
> +	      not any of <filename>cc</filename>, <filename>c99</filename>,
> +	      <filename>gcc</filename>, <filename>c++</filename>, or
> +	      <filename>g++</filename> directly.</para>

What shouldn't we do with 'cc' 'c99' etc? I think we should be more specific here in terms of
'do not use <filename>cc</filename>[..] directly.

> +	  </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>

^^^ add :

> +
> +	    <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>


Thanks for making this!

-- 
/"\   Best regards,                        | remko at FreeBSD.org
\ /   Remko Lodder                      | remko at EFnet
X    http://www.evilcoder.org/    |
/ \   ASCII Ribbon Campaign    | Against HTML Mail and News