incubator-ooo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ksch...@apache.org
Subject svn commit: r1175537 [3/3] - /incubator/ooo/ooo-site/trunk/content/tools/
Date Sun, 25 Sep 2011 19:39:09 GMT
Added: incubator/ooo/ooo-site/trunk/content/tools/coding.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/coding.html?rev=1175537&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/tools/coding.html (added)
+++ incubator/ooo/ooo-site/trunk/content/tools/coding.html Sun Sep 25 19:39:08 2011
@@ -0,0 +1,678 @@
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+   <meta http-equiv="CONTENT-TYPE" content="text/html; charset=iso-8859-1">
+</head>
+<body>
+
+<table BORDER=0 CELLSPACING=0 CELLPADDING=3 WIDTH="100%" STYLE="page-break-before: always" >
+<tr>
+<td VALIGN=TOP>
+<h1><a NAME="portability_rules"></a>C++ coding guidelines</h1>
+The <a href="http://www.mozilla.org/hacking/portable-cpp.html">Mozilla
+C++ portability guidelines</a> provide an excellent source of information
+on portable C++ programming. Many of these guidelines are direct applicable
+to coding OpenOffice.org projects and are taken over verbatim into the
+guidelines below. I've taken out some of the Mozilla rules
+(don't use exceptions,
+RTTI and namespaces) which restrict the usage of newer language features.
+OpenOffice.org can't be compiled with older compilers anyway, and current
+compilers implement these features properly. I've also added a few rules
+from our OpenOffice.org programming guidelines.
+<p>The guidelines are roughly ordered by importance. Guideline 1,2,4,5
+cover problems which are almost always present in any mayor build of OpenOffice.org
+and require sometimes excessive amount of code tweaking by the release
+engineers.
+<br>
+<h2><a NAME="dont_use_static_constructors"></a>Don't use static constructors.</h2>
+<p>Non-portable example:
+<pre>
+  FooBarClass static_object(87, 92);
+
+  void
+  bar()
+  {
+    if (static_object.count &gt; 15) {
+       ...
+    }
+  }
+</pre>
+Static constructors don't work reliably either. A static initialized object
+is an object which is instanciated at startup time (just before <tt>main()</tt>
+is called). Usually there are two components to these objects. First there
+is the data segment which is static data loaded into the global data segment
+of the program. The second part is a initializer function that is called
+by the loader before <tt>main()</tt> is called. We've found that many compilers
+do not reliably implement the initializer function. So you get the object
+data, but it is never initialized. One workaround for this limitation is
+to write a wrapper function that creates a single instance of an object,
+and replace all references to the static initialized object with a call
+to the wrapper function:
+<p>Portable example:
+<pre>
+  static FooBarClass* static_object;
+
+  FooBarClass*
+  getStaticObject()
+  {
+    if (!static_object)
+      static_object =
+        new FooBarClass(87, 92);
+    return static_object;
+  }
+
+  void
+  bar()
+  {
+    if (getStaticObject()-&gt;count &gt; 15) {
+      ...
+    }
+  }
+</pre>
+<h2><a NAME="use_common_den"></a>Use the common denominator between members
+of a C/C++ compiler family.</h2>
+<p>For many of the compiler families we use, the implementation of the
+C and C++ compilers are completely different, sometimes this means that
+there are things you can do in the C language, that you cannot do in the
+C++ language on the same machine. One example is the 'long long' type.
+On some systems (IBM's compiler used to be one, but I think it's better
+now), the C compiler supports long long, while the C++ compiler does not.
+This can make porting a pain, as often times these types are in header
+files shared between C and C++ files. The only thing you can do is to go
+with the common denominator that both compilers support. In the special
+case of long long, we developed a set of macros for supporting 64 bit integers
+when the long long type is not available. We have to use these macros if
+either the C or the C++ compiler does not support the special 64 bit type.
+<h2><a NAME="no_cpp_comments_in_c"></a>Don't put C++ comments in C code.</h2>
+<p>The quickest way to raise the blood pressure of a Release engineer is
+to put C++ comments (<b><tt>//</tt></b> comments) into C files. Yes, this
+might work on your Microsoft Visual C compiler, but it's wrong, and is
+not supported by the vast majority of C compilers in the world.<b> Just
+do not go there.</b>
+<p>Many header files will be included by C files and included by C++ files.
+We think it's a good idea to apply this same rule to those headers. Don't
+put C++ comments in header files included in C files. You might argue that
+you could use C++ style comments inside <tt>#ifdef __cplusplus</tt> blocks,
+but we are not convinced that is always going to work (some compilers have
+weird interactions between comment stripping and pre-processing), and it
+hardly seems worth the effort. Just stick to C style <tt>/**/</tt> comments
+for any header file that is ever likely to be included by a C file.
+<h2><a NAME="put_new_line_at_eof"></a>Put a new line at end-of-file.</h2>
+<p>Not having a new-line char at end-of-file breaks some compilers (Solaris).
+<h2><a NAME="no_extra_semi_colons"></a>Don't put extra top-level semi-colons
+in code.</h2>
+<p>Non-portable example:
+<pre>
+  int
+  A::foo()
+  {
+  };
+</pre>
+This is another problem that seems to show up more on C++ than C code.
+This is problem really a bit of a drag. That extra little semi-colon at
+the end of the function is ignored by most compilers, but it makes some
+compilers very unhappy (IBM's AIX compiler doesn't like extra top-level
+semi-colons). Don't do it.
+<p>Portable example:
+<pre>
+  int
+  A::foo()
+  {
+  }
+</pre>
+<h2><a NAME="file_extension_is_cpp"></a>C++ filename extension is <tt>.cxx</tt>.</h2>
+<p>This one is another plain annoying problem. What's the name of a C++
+file? <tt>file.cpp</tt>, <tt>file.cc</tt>, <tt>file.C</tt>, <tt>file.cxx</tt>,
+<tt>file.c++</tt>,
+<tt>file.C++</tt>?
+Most compilers could care less, but some are very particular. We have not
+been able to find one file extension which we can use on all the platforms
+we have ported OpenOffice.org code to. For no great reason, we've settled
+on <tt>file.cxx</tt>, probably because the first C++ code in OpenOffice.org
+code was checked in with that extension. Well, it's done. The extension
+we use is <tt>.cxx</tt>. This extension seems to make most compilers happy,
+but there are some which do not like it.
+<h2><a NAME="dont_use_init_lists_with_cpp"></a>Don't use initializer
+lists with objects.</h2>
+<p>Non-portable example:
+<pre STYLE="margin-bottom: 0.2in">  FooClass myFoo = {10, 20};</pre>
+Some compilers won't allow this syntax for objects (HP-UX won't), actually
+only some will allow it. So don't do it. Again, use a wrapper function,
+see <a href="http://www.mozilla.org/hacking/portable-cpp.html#dont_use_static_constructors">Don't
+use static constructors.</a>
+<h2><a NAME="always_have_default_constructor"></a>Always have a default
+constructor.</h2>
+<p>Always have a default constructor, even if it doesn't make sense in
+terms of the object structure/hierarchy. HP-UX will barf on statically
+initialized objects that don't have default constructors.
+<h2><a NAME="inner_classes"></a>Be careful with inner-classes.</h2>
+<p>Some compilers (HP-UX) generally require that types (classes, enums,
+etc.) declared inside of another class should be referred to with their
+fully scoped form (e.g., <tt>Foo::kListMaxLen</tt> versus <tt>kListMaxLen</tt>).
+<h2><a NAME="init_variables_at_top"></a>Be careful of variable declarations
+that require construction or initialization.</h2>
+<p>Non-portable example:
+<pre>
+  void
+  A::foo(int c)
+  {
+    switch(c) {
+    case FOOBAR_1:
+      XyzClass buf(100);
+      // <i>stuff
+</i>      break;
+    }
+  }
+</pre>
+Be careful with variable placement around if blocks and switch statements.
+Some compilers (HP-UX) require that any variable requiring a constructor/initializer
+to be run, needs to be at the start of the method -- it won't compile code
+when a variable is declared inside a switch statement and needs a default
+constructor to run.
+<p>Portable example:
+<pre>
+  void
+  A::foo(int c)
+  {
+    XyzClass buf(100);
+
+    switch(c) {
+    case FOOBAR_1:
+      // <i>stuff</i>
+      break;
+    }
+  }
+</pre>
+<h2><a NAME="header_files_c_and_cpp"></a>Make header files compatible with
+C and C++.</h2>
+<p>Non-portable example:
+<pre>
+  /*<i>oldCheader.h</i>*/
+  int existingCfunction(char*);
+  int anotherExistingCfunction(char*);
+
+  /*<i> oldCfile.c </i>*/
+  #include "oldCheader.h"
+  ...
+
+  // <i>new file.cxx</i>
+  extern "C" {
+  #include "oldCheader.h"
+  };
+  ...
+</pre>
+If you make new header files with exposed C interfaces, make the header
+files work correctly when they are included by both C and C++ files. If
+you start including an existing C header in new C++ files, fix the C header
+file to support C++ (as well as C), don't just <tt>extern "C" {}</tt> the
+old header file. Do this:
+<p>Portable example:
+<pre>
+  /*<i>oldCheader.h</i>*/
+  #ifdef __cplusplus
+  extern "C" {
+  #endif
+  int existingCfunction(char*);
+  int anotherExistingCfunction(char*);
+  #ifdef __cplusplus
+  }
+  #endif
+
+  /*<i> oldCfile.c </i>*/
+  #include "oldCheader.h"
+  ...
+
+  // <i>new file.cxx</i>
+  #include "oldCheader.h"
+  ...
+</pre>
+There are number of reasons for doing this, other than just good style.
+For one thing, you are making life easier for everyone else, doing the
+work in one common place (the header file) instead of all the C++ files
+that include it. Also, by making the C header safe for C++, you document
+that "hey, this file is now being included in C++". That's a good thing.
+You also avoid a big portability nightmare that is nasty to fix...
+<p>Some systems include C++ in system header files that are designed to
+be included by C or C++. Not just <tt>extern "C" {}</tt> guarding, but
+actual C++ code, usually in the form of inline functions that serve as
+"optimizations". While we question the wisdom of vendors doing this, there
+is nothing we can do about it. Changing system header files, is not a path
+we wish to take. Anyway, so why is this a problem? Take for example the
+following code fragment:
+<p>Non-portable example:
+<pre>
+  /*<i>system.h</i>*/
+  #ifdef __cplusplus
+    /*<i> optimization </i>*/
+  inline int sqr(int x) {return(x*x);}
+  #endif
+
+  /*<i>header.h</i>*/
+  #include &lt;system.h&gt;
+  int existingCfunction(char*);
+
+  // <i>file.cxx </i>
+  extern "C" {
+  #include "header.h"
+  }
+</pre>
+What's going to happen? When the C++ compiler finds the <tt>extern "C"</tt>
+declaration in <tt>file.cxx</tt>, it will switch dialects to C, because
+it's assumed all the code inside is C code, and C's type free name rules
+need to be applied. But the __cplusplus pre-processor macro is still defined
+(that's seen by the pre-processor, not the compiler). In the system header
+file the C++ code inside the <tt>#ifdef __cplusplus</tt> block will be
+seen by the compiler (now running in C mode). Syntax Errors galore! If
+instead the <tt>extern "C"</tt> was done in the header file, the C functions
+can be correctly guarded, leaving the systems header file out of the equation.
+This works:
+<p>Portable example:
+<pre>
+  /*<i>system.h</i>*/
+  #ifdef __cplusplus
+    /*<i> optimization </i>*/
+  inline int sqr(int x) {return(x*x);}
+  #endif
+
+  /*<i>header.h</i>*/
+  #include &lt;system.h&gt;
+  extern "C" {
+  int existingCfunction(char*);
+  }
+
+  // <i>file.cxx</i>
+  #include "header.h"
+</pre>
+One more thing before we leave the <tt>extern "C"</tt> segment of the program.
+Sometimes you're going to have to <tt>extern "C"</tt> system files. This
+is because you need to include C system header files that do not have <tt>extern
+"C"</tt> guarding themselves. Most vendors have updated all their headers
+to support C++, but there are still a few out there that won't grok C++.
+You might have to do this only for some platforms, not for others (using
+<tt>#ifdef
+SYSTEM_X</tt>). The safest place to do <tt>extern "C"</tt> a system header
+file (in fact the safest place to include a system header file) is at the
+lowest place possible in the header file inclusion hierarchy. That is,
+push all this stuff down to the header files closer to the system code,
+don't do this stuff in the mail header files. Ideally the best place to
+do this is in the NSPR or XP header files - which sit directly on the system
+code.
+<h2><a NAME="variables_in_for"></a>Be careful of the scoping of variables
+declared inside <tt>for()</tt> statements.</h2>
+<p>Non-portable example:
+<pre>
+  void
+  A::foo()
+  {
+      for (int i = 0; i &lt; 10; i++) {
+        // <i>do something</i>
+      }
+      // <i><b>i</b> might get referenced</i>
+      // <i> after the loop.</i>
+      ...
+  }
+</pre>
+This is actually an issue that comes about because the C++ standard has
+changed over time. The original C++ specification would scope the <b>i</b>
+as part of the outer block (in this case function <tt>A::foo()</tt>). The
+standard changed so that now the <b>i</b> in is scoped within the <tt>for()
+{}</tt> block. Most compilers use the new standard. Some compilers (for
+example, HP-UX) still use the old standard. Some other compilers (for example,
+gcc) use the new rules, but will tolerate the old. If <b>i</b> was referenced
+later in the <tt>for() {}</tt> block, gcc will allow the construct, but
+give a warning about use of an "obsolete binding". So, while the code above
+is valid, it would become ambiguous if <b>i</b> was used later in the function.
+It's probably better to be on the safe side and declare the iterator variable
+outside of the <tt>for()</tt> loop. Then you'll know what you are getting
+on all platforms:
+<p>Portable example:
+<pre>
+  void
+  A::foo()
+  {
+    int i;
+    for (i = 0; i &lt; 10; i++) {
+      // <i>do something</i>
+    }
+    // <i><b>i</b> might get referenced</i>
+    // <i> after the loop.</i>
+	...
+  }
+</pre>
+<h2><a NAME="local_aggregates"></a>Declare local initialized aggregates
+as static.</h2>
+<p>Non-portable example:
+<pre>
+  void
+  A:: func_foo()
+  {
+    char* foo_int[] = {"1", "2", "C"};
+    ...
+  }
+</pre>
+This seemingly innocent piece of code will generate a "loader error" using
+the HP-UX compiler/linker. If you really meant for the array to be static
+data, say so:
+<p>Portable example:
+<pre>
+  void
+  A:: func_foo()
+  {
+    static char *foo_int[] = {"1", "2", "C"};
+    ...
+  }
+</pre>
+Otherwise you can keep the array as an automatic, and initialize by hand:
+<p>Portable example:
+<pre>
+  void
+  A:: func_foo()
+  {
+    char *foo_int[3];
+
+    foo_int[0] = XP_STRDUP("1");
+    foo_int[1] = XP_STRDUP("2");
+    foo_int[2] = XP_STRDUP("C");
+    // <i>or something equally Byzantine...</i>
+    ...
+  }
+</pre>
+<h2><a NAME="complex_inlines"></a>Expect complex inlines to be non-portable.</h2>
+<p>Non-portable example:
+<pre>
+  class FooClass {
+    ...
+    int fooMethod(char* p) {
+      if (p[0] == '\0')
+        return -1;
+
+      doSomething();
+      return 0;
+    }
+    ...
+  };
+</pre>
+It's surprising, but many C++ compilers do a very bad job of handling inline
+member functions. Cfront based compilers (like those on SCO and HP-UX)
+are prone to give up on all but the most simple inline functions, with
+the error message "sorry, unimplemented". Often times the source of this
+problem is an inline with multiple return statements. The fix for this
+is to resolve the returns into a single point at the end of the function.
+But there are other constructs which will result in "not implemented".
+For this reason, you'll see that most of the C++ code in Mozilla does not
+use inline functions. We don't want to legislate inline functions away,
+but you should be aware that there is some danger in using them, so do
+so only when there is some measurable gain (not just a random hope of performance
+win). <b>Maybe you should just not go there.</b>
+<p>Portable example:
+<pre>
+  class FooClass {
+    ...
+    int fooMethod(char* p) {
+      int return_value;
+
+        if (p[0] == '\0') {
+           return_value = -1;
+        } else {
+           doSomething();
+           return_value = 0;
+        }
+        return return_value;
+    }
+    ...
+  };
+</pre>
+Or
+<p>Portable example:
+<pre>
+  class FooClass {
+    ...
+    int fooMethod(char* p);
+    ...
+  };
+
+  int FooClass::fooMethod(char* p)
+  {
+    if (p[0] == '\0')
+      return -1;
+
+    doSomething();
+    return 0;
+  }
+</pre>
+<h2><a NAME="inlines_in_return"></a>Don't use return statements that have
+an inline function in the return expression.</h2>
+<p>For the same reason as the previous tip, don't use return statements
+that have an inline function in the return expression. You'll get that
+same "sorry, unimplemented" error. Store the return value in a temporary,
+then pass that back.
+<h2><a NAME="virtual_on_subclasses"></a>Use virtual declaration on all
+subclass virtual member functions.</h2>
+<p>Non-portable example:
+<pre>
+  class A {
+    virtual void foobar(char*);
+  };
+
+  class B : public A {
+    void foobar(char*);
+  };
+</pre>
+Another drag. In the class declarations above, <tt>A::foobar()</tt> is
+declared as virtual. C++ says that all implementations of void <tt>foobar(char*)</tt>
+in subclasses will also be virtual (once virtual, always virtual). This
+code is really fine, but some compilers want the virtual declaration also
+used on overloaded functions of the virtual in subclasses. If you don't
+do it, you get warnings. While this is not a hard error, because this stuff
+tends to be in headers files, you'll get so many warnings that's you'll
+go nuts. Better to silence the compiler warnings, by including the virtual
+declaration in the subclasses. It's also better documentation:
+<p>Portable example:
+<pre>
+  class A {
+    virtual void foobar(char*);
+  };
+
+  class B : public A {
+    virtual void foobar(char*);
+  };
+</pre>
+<h2><a NAME="copy_constructors"></a>Always declare a copy constructor and
+assignment operator.</h2>
+<p>One feature of C++ that can be problematic is the use of copy constructors.
+Because a class's copy constructor defines what it means to pass and return
+objects by value (or if you prefer, pass by value means call the copy constructor),
+it's important to get this right. There are times when the compiler will
+silently generate a call to a copy constructor, that maybe you do not want.
+For example, when a you pass an object by value as a function parameter,
+a temporary copy is made, which gets passed, then destroyed on return from
+the function. Maybe you don't want this to happen, maybe you'd always like
+instances of your class to be passed by reference. If you do not define
+a copy constructor the C++ compiler will generate one for you (the default
+copy constructor), and this automatically generated copy constructor might,
+well, suck. So you have a situation where the compiler is going to silently
+generate calls to a piece of code that might not be the greatest code for
+the job (it may be wrong).
+<p>Ok, you say, "no problem, I know when I'm calling the copy constructor,
+and I know I'm not doing it". But what about other people using your class?
+The safe bet is to do one of two things: if you want your class to support
+pass by value, then write a good copy constructor for your class. If you
+see no reason to support pass by value on your class, then you should explicitly
+prohibit this, don't let the compiler's default copy constructor do it
+for you. The way to enforce your policy is to declare the copy constructor
+as private, and not supply a definition. While your at it, do the same
+for the assignment operator used for assignment of objects of the same
+class. Example:
+<pre>
+  class foo {
+    ...
+    private:
+    // <i>These are not supported</i>
+    // <i>and are not implemented!</i>
+    foo(const foo&amp; x);
+    foo&amp; operator=(const foo&amp; x);
+  };
+</pre>
+When you do this, you ensure that code that implicitly calls the copy constructor
+will not compile and link. That way nothing happens in the dark. When a
+user's code won't compile, they'll see that they were passing by value,
+when they meant to pass by reference (oops).
+<h2><a NAME="signatures"></a>Be careful of overloaded methods with like
+signatures.</h2>
+<p>It's best to avoid overloading methods when the type signature of the
+methods differs only by 1 "abstract" type (e.g. <tt>PR_Int32</tt> or <tt>int32</tt>).
+What you will find as you move that code to different platforms, is suddenly
+on the Foo2000 compiler your overloaded methods will have the same type-signature.
+<h2><a NAME="type_scalar_constants"></a>Type scalar constants to avoid
+unexpected ambiguities.</h2>
+<p>Non-portable code:
+<pre>
+  class FooClass {
+    // <i>having such similar signatures</i>
+    // <i>is a bad idea in the first place.</i>
+    void doit(long);
+    void doit(short);
+  };
+
+  void
+  B::foo(FooClass* xyz)
+  {
+    xyz-&gt;doit(45);
+  }
+</pre>
+Be sure to type your scalar constants, e.g., PR_INT32(10) or 10L. Otherwise,
+you can produce ambiguous function calls which potentially could resolve
+to multiple methods, particularly if you haven't followed (2) above. Not
+all of the compilers will flag ambiguous method calls.
+<p>Portable code:
+<pre>
+  class FooClass {
+    // <i>having such similar signatures</i>
+    // <i>is a bad idea in the first place.</i>
+    void doit(long);
+    void doit(short);
+  };
+
+  void
+  B::foo(FooClass* xyz)
+  {
+    xyz-&gt;doit(45L);
+  }
+</pre>
+<h2><a NAME="bool_types"></a>Type scalar constants to avoid unexpected ambiguities.</h2>
+<p>Some platforms (e.g. Linux) have native definitions of types like bool
+which sometimes conflict with definitions OpenOffice.org code. Always use
+sal_Bool..
+
+<h1><a NAME="c_and_cplusplus"></a>Stuff that is good to do for C or C++.</h1>
+
+<h2><a NAME="dont_ifdef_include"></a>Do not wrap include statements
+with an <tt>#ifdef</tt>.</h2>
+<p>Do not wrap include statements with an <tt>#ifdef</tt>. The reason is
+that when the symbol is not defined, other compiler symbols will not be
+defined and it will be hard to test the code on all platforms. An example
+of what not to do:
+<p>Bad code example:
+<pre>
+  // don't do this
+  #ifdef X
+  #include "foo.h"
+  #endif
+</pre>
+The exception to this rule is when you are including different system files
+for different machines. In that case, you may need to have a <tt>#ifdef
+SYSTEM_X</tt> include.
+<h2><a NAME="assignments_in_boolean"></a>Macs complain about assignments
+in boolean expressions.</h2>
+<p>Another example of code that will generate warnings on a Mac:
+<p>Generates warnings code:
+<pre STYLE="margin-bottom: 0.2in">  if ((a = b) == c) ...</pre>
+Macs don't like assignments in <b>if</b> statements, even if you properly
+wrap them in parentheses.
+<p>More portable example:
+<pre>
+  a=b;
+  if (a == c) ...
+</pre>
+<h2><a NAME="filenames_must_be_unique"></a>Every source file must have a
+unique name.</h2>
+<p>Non-portable file tree:
+<pre>
+  feature_x
+      private.h
+      x.cxx
+  feature_y
+      private.h
+      y.cxx
+</pre>
+For Mac compilers, every has to have a unique name. Don't assume that just
+because your file is only used locally that it's OK to use the same name
+as a header file elsewhere. It's not ok. Every filename must be different.
+<p>Portable file tree:
+<pre>
+  feature_x
+      xprivate.h
+      x.cxx
+  feature_y
+      yprivate.h
+      y.cxx
+</pre>
+<b>Use <tt>#if 0</tt> rather than comments to temporarily kill blocks of
+code.</b>
+<p>Non-portable example:
+<pre>
+  int
+  foo()
+  {
+    ...
+    a = b + c;
+    /*
+     * Not doing this right now.
+    a += 87;
+    if (a &gt; b) (* have to check for the
+                  candy factor *)
+      c++;
+     */
+    ...
+  }
+</pre>
+This is a bad idea, because you always end up wanting to kill code blocks
+that include comments already. No, you can't rely on comments nesting properly.
+That's far from portable. You have to do something crazy like changing
+<tt>/**/</tt>
+pairs to <tt>(**)</tt> pairs. You'll forget. And don't try using <tt>#ifdef
+NOTUSED</tt>, the day you do that, the next day someone will quietly start
+defining <tt>NOTUSED</tt> somewhere. It's much better to block the code
+out with a <tt>#if 0</tt>, <tt>#endif</tt> pair, and a good comment at
+the top. Of course, this kind of thing should always be a temporary thing,
+unless the blocked out code fulfills some amazing documentation purpose.
+<p>Portable example:
+<pre>
+  int
+  foo()
+  {
+    ...
+    a = b + c;
+  #if 0
+    /*<i> Not doing this right now. </i>*/
+    a += 87;
+    if (a &gt; b) /*<i> have to check for the
+                  candy factor </i>*/
+      c++;
+  #endif
+    ...
+  }
+</pre>
+<h2>Source code formatting.</h2>
+<p>After some discussion we agreed that basic indentation should be four
+spaces, no tabs. Please use an editor setting which expands a typed tab
+into spaces. Some examples:</p><br>
+<code>vim: set expandtab</code><br>
+<code>emacs: (setq-default indent-tabs-mode nil)</code><br>
+<code>msdev: check Options-&gt;Tabs-&gt;Insert Spaces</code><br>
+</td>
+</tr>
+</table>
+</body>
+</html>

Propchange: incubator/ooo/ooo-site/trunk/content/tools/coding.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/ooo/ooo-site/trunk/content/tools/depend.gif
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/depend.gif?rev=1175537&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/ooo/ooo-site/trunk/content/tools/depend.gif
------------------------------------------------------------------------------
    svn:mime-type = image/gif

Added: incubator/ooo/ooo-site/trunk/content/tools/ext_comp.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/ext_comp.html?rev=1175537&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/tools/ext_comp.html (added)
+++ incubator/ooo/ooo-site/trunk/content/tools/ext_comp.html Sun Sep 25 19:39:08 2011
@@ -0,0 +1,175 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<HTML>
+<HEAD>
+	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1251">
+	<TITLE>External Components</TITLE>
+	<META NAME="GENERATOR" CONTENT="OpenOffice.org 1.1  (Win32)">
+	<META NAME="CREATED" CONTENT="20030522;19110663">
+	<META NAME="CHANGED" CONTENT="20030523;14215217">
+</HEAD>
+<BODY LANG="en-US" DIR="LTR">
+<h1>External Components</h1>
+<P>There are several external components which are used to build the
+office suite. Most of the external components are in the source tree,
+so you do not have to download them separately. For further external
+download information, see the appropriate  build guide for your platform
+referenced from the <a HREF="index.html">main tools page</a>.
+</P>
+<p>It is possible to build using the system versions of the external modules
+Please see <code>configure --help</code> for the options to use the system
+versions.  This is especially valuable to packagers of Openoffice.org.</p>
+<P>Most of these external components are gzipped tarballs. These
+external tarballs are in the <CODE>&lt;name&gt;/download</CODE> directory
+under the source tree top-level directory.  Some are stored in the external
+directory under <code>external/download</code> because they have not migrated
+to this new directory structure.
+</P>
+<P>These modules are built throughout the build process.
+Early in the build process it will also process build the 
+<CODE>external</CODE> module. The process extracts the tarballs. In
+some cases it patches with specific OpenOffice.org patches.  It then compiles
+the components. The deliver program then copies the
+components into the <CODE>solver</CODE> tree. 
+</P>
+<P>If the correct external components are not present in your source
+tree, the build will not work. Some of these external components are
+platform-dependent. That is, you do not need all of them if you are
+not building on that particular platform. If the required components
+are present, the build process writes a text file called <CODE>patchinf</CODE>
+to the <CODE>external/</CODE><VAR>component-name</VAR> directory. If
+the required components are not present, the build process writes a
+text file called <CODE>patcherror</CODE> to the
+<CODE>external/</CODE><VAR>component-name</VAR> directory. The
+<CODE>patcherror</CODE> file specifies what components are missing,
+and where they are missing from. 
+</P>
+<P>In some instances the original tarballs have been minimized to
+include only the relevant files. These tarballs have been renamed
+with a <CODE>-stub</CODE> suffix. The stub tarball version is an
+attempt to save space and reduce the download time. If you want to
+use the original tarballs, you must modify the appropriate patch
+script in the <CODE>external/</CODE><VAR>component-name</VAR>
+directory. 
+</P>
+<P><B>ADO</B></P>
+<P>Platform: Win32</P>
+<P>Version: Microsoft Platforms SDK, April 2000 Edition</P>
+<P>URL:
+<A HREF="http://www.microsoft.com/msdownload/platformsdk/setuplauncer.htm">http://www.microsoft.com/msdownload/platformsdk/setuplauncer.htm</A></P>
+<P>Notes: Download the Platform SDK Setup, <CODE>psdk-86.exe</CODE>,
+from the Custom Installation section. Then run it in your Win32
+environment. This starts an interactive download program. <BR>Follow
+the instructions on the screen. At the Custom Installation screen,
+select Build Environment/Data Access Service/OLE DB from the Custom
+Installation tree. This downloads a number of files to your Win32
+environment. You only need to copy the header file <CODE>adoctint.h</CODE>
+to the <CODE>external/download</CODE> directory under the source tree
+top-level directory. 
+</P>
+<P><B>Network Audio System (audio)</B></P>
+<P>Platform: Linux, Solaris</P>
+<P>Version: 1.6</P>
+<P>URL: <A HREF="http://www.radscan.com/nas.html">http://www.radscan.com/nas.html</A></P>
+<P><B>Dmake - Build Environment Tool</B></P>
+<P>Platform: All</P>
+<P>Version: 3.2.1</P>
+<P>URL: <A HREF="http://www.wticorp.com/projects/dmake">http://www.wticorp.com/projects/dmake</A></P>
+<p>This link is dead.  OpenOffice.org has taken over this project.</p>
+<P><B>XML Parser Toolkit (expat)</B></P>
+<P>Platform: All</P>
+<P>Version: 1.2</P>
+<P>URL: <A HREF="ftp://ftp.jclark.com/pub/xml/expat.zip">ftp://ftp.jclark.com/pub/xml/expat.zip</A></P>
+<P>Notes: For more information, see
+<A HREF="http://www.jclark.com/xml/expat.html">http://www.jclark.com/xml/expat.html</A>.</P>
+<P><B>Glibc - command line parsing&lt;</B></P>
+<P>Platform: All</P>
+<P>Version: 2.1.3</P>
+<P>URL: <A HREF="ftp://ftp.gnu.org/gnu/glibc/glibc-2.1.3.tar.gz">ftp://ftp.gnu.org/gnu/glibc/glibc-2.1.3.tar.gz</A></P>
+<P>Notes: For more information, see <A HREF="http://www.gnu.org/">http://www.gnu.org</A>. Stub stored in internal.</P>
+<P><B>JPEG Image Compression</B></P>
+<P>Platform: All</P>
+<P>Version: 6b</P>
+<P>URL: <A HREF="ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz">ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz</A></P>
+<P>Notes: For more information, see <A HREF="http://www.ihg.org/">http://www.ijg.org</A>.</P>
+<P><B>NP_SDK</B></P>
+<P>Platform: All</P>
+<P>Version: Mozilla Milestone 16</P>
+<P>URL:
+<A HREF="http://www.mozilla.org/projects/seamonkey/release-notes/index.html">http://www.mozilla.org/projects/seamonkey/release-notes/index.html</A></P>
+<P>Notes: You must get the M16 tarball.</P>
+<P><B>ODBC</B></P>
+<P>Platform: Win32</P>
+<P>Version: 3.0</P>
+<P>URL:
+<A HREF="http://www.microsoft.com/msdownload/platformsdk/setuplauncer.htm">http://www.microsoft.com/msdownload/platformsdk/setuplauncer.htm</A></P>
+<P>Notes: Download the Platform SDK Setup, <CODE>psdk-86.exe</CODE>,
+from the Custom Installation section. Then run it in your Win32
+environment. This starts an interactive download program. <BR>Follow
+the instructions on the screen. At the Custom Installation screen,
+select Build Environment/Data Access Service/OLE DB from the Custom
+Installation tree. This downloads a number of files to your Win32
+environment. You only need to copy the header file <CODE>SqlUcode.h</CODE>
+to the <CODE>external/download</CODE> directory under the source tree
+top-level directory. 
+</P>
+<P><B>PGP</B></P>
+<P>Platform: Win32</P>
+<P>Version: 5.5, 6.0, and 6.5</P>
+<P>URL:
+<BR><A HREF="http://www.pgpi.org/products/pgp/versions/freeware/win32/5.5.3i/">
+http://www.pgpi.org/products/pgp/versions/freeware/win32/5.5.3i</A><BR>
+<A HREF="http://www.pgpi.org/products/pgp/versions/freeware/win32/6.0.2i/">
+http://www.pgpi.org/products/pgp/versions/freeware/win32/6.0.2i</A><BR>
+<A HREF="http://www.pgpi.org/products/pgp/versions/freeware/win32/6.5.1i/">
+http://www.pgpi.org/products/pgp/versions/freeware/win32/6.5.1i</A>
+</P>
+<P>Notes: You must download the soure tarballs for all three versions
+of PGP.</P>
+<P><B>Sane</B></P>
+<P>Platform: All</P>
+<P>Version: 1.0</P>
+<P>URL: <A HREF="http://www.mostang.com/sane/source.html">http://www.mostang.com/sane/source.html</A>
+</P>
+<P>Notes: Get the <CODE>sane-1.00.tar.gz</CODE> file.</P>
+<P><B>STLPort - C++ Standard Template Library (Std2)</B></P>
+<P>Platform: All</P>
+<P>Version: 4.0 4.5 &amp; 4.5.3</P>
+<P>URL: <A HREF="http://www.stlport.org/download.shtml">http://www.stlport.org/download.shtml</A>
+</P>
+<P>Notes: For more information, see <A HREF="http://www.stlport.org/">http://www.stlport.org</A></P>
+<P><B>Twain</B></P>
+<P>Platform: All</P>
+<P>Version: 1.9</P>
+<P>URL: <A HREF="http://www.twain.org/devfiles/twain.h">http://www.twain.org/devfiles/twain.h</A>
+</P>
+<P>Notes: You only need to download the <CODE>twain.h</CODE> header
+file.</P>
+<P><B>Zlib Compression Library</B></P>
+<P>Platform: All</P>
+<P>Version: 1.1.3</P>
+<P>URL: <A HREF="ftp://ftp.uu.net/pub/archiving/zip/zlib/zlib.tar.gz">ftp://ftp.uu.net/pub/archiving/zip/zlib/zlib.tar.gz</A>
+</P>
+<P>Notes: For more information, see
+<A HREF="http://www.info-zip.org/pub/infozip/zlib/">http://www.info-zip.org/pub/infozip/zlib</A>.</P>
+<P><B>Neon</B></P>
+<P>Platform: All</P>
+<P>Version: 0.23.5</P>
+<P>URL: <A HREF="http://www.webdav.org/neon/">http://www.webdav.org/neon</A>
+</P>
+<P><B>PATCH (GNU)</B></P>
+<P>Platform: Solaris</P>
+<P>Version: 2.5.4</P>
+<P>URL: <A HREF="http://ftp.gnu.org/pub/gnu/patch/patch-2.5.4.tar.gz">http://ftp.gnu.org/pub/gnu/patch/patch-2.5.4.tar.gz</A></P>
+<P>Notes: There is patch program in Solaris system. Make sure that in
+your build environment the GNU patch is used (Just run &ldquo;patch
+-v&rdquo; to prove it).</P>
+	<a name="gperf"></a><P><B>gperf (GNU)</B>
+	</P>
+	<P>Platform: All</P>
+	<P>Version: 3.0.3</P>
+	<P>URL Linux: <A HREF="ftp://ftp.gnu.org/pub/gnu/gperf/gperf-3.0.3.tar.gz">ftp://ftp.gnu.org/pub/gnu/gperf/gperf-3.0.3.tar.gz</A></P>
+	<p>URL Windows: <A HREF="http://gnuwin32.sourceforge.net/packages/gperf.htm">http://gnuwin32.sourceforge.net/packages/gperf.htm</A></p>
+	<p>URL Solaris: <A HREF="ftp://gd.tuwien.ac.at/platform/sun/solaris/freeware/intel/10/gperf-3.0.3-sol10-x86-local.gz">ftp://gd.tuwien.ac.at/platform/sun/solaris/freeware/intel/10/gperf-3.0.3-sol10-x86-local.gz</A></p>
+	<P>Notes: For more information see <a href="http://www.gnu.org/software/gperf/gperf.html">http://www.gnu.org/software/gperf/gperf.html</a>.</P>
+</BODY>
+</HTML>

Propchange: incubator/ooo/ooo-site/trunk/content/tools/ext_comp.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/ooo/ooo-site/trunk/content/tools/favicon.ico
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/favicon.ico?rev=1175537&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/ooo/ooo-site/trunk/content/tools/favicon.ico
------------------------------------------------------------------------------
    svn:mime-type = image/x-icon

Added: incubator/ooo/ooo-site/trunk/content/tools/flow1.gif
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/flow1.gif?rev=1175537&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/ooo/ooo-site/trunk/content/tools/flow1.gif
------------------------------------------------------------------------------
    svn:mime-type = image/gif

Added: incubator/ooo/ooo-site/trunk/content/tools/flow2.gif
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/flow2.gif?rev=1175537&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/ooo/ooo-site/trunk/content/tools/flow2.gif
------------------------------------------------------------------------------
    svn:mime-type = image/gif

Added: incubator/ooo/ooo-site/trunk/content/tools/index.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/index.html?rev=1175537&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/tools/index.html (added)
+++ incubator/ooo/ooo-site/trunk/content/tools/index.html Sun Sep 25 19:39:08 2011
@@ -0,0 +1,162 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+  <title>OpenOffice.org Tools Project</title>
+  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
+</head>
+<body>
+<h1>Tools Project</h1>
+
+<div style="padding:3pt; background-color: #f8d3d0; margin-top: 4pt; margin-bottom: 4pt;">
+<h2>Warning</h2>
+<p>Much of the information here is <b>outdated</b> and refers to obsolete OOo versions.</p>
+<p>For current information on how to build OOo, see the OOo Wiki:
+   <a href="http://wiki.services.openoffice.org/wiki/Documentation/Building_Guide">Building Guide</a></p>
+</div>
+
+<h3>Build Environment<a name="CWS"></a>
+</h3>
+<h4>Using CVS to get ancient versions of the source</h4>
+<ul>
+  <li> <a href="http://development.openoffice.org/releases/index.html">Overview
+of OpenOffice.org codelines</a> </li>
+  <li> <a href="builds/index.html">Descriptions of current CVS
+branches and their status</a></li>
+  <li><a href="svn_checkout.html">Downloading the source from the
+Subversion repository</a> (only useful for getting the OOo 3.1 release branch)<br>
+  </li>
+  <li> <a href="http://tools.openoffice.org/servlets/ProjectSource">Downloading
+the source from CVS</a> for releases until OOo 3.0<br>
+  </li>
+  <li> <a
+ href="http://wiki.services.openoffice.org/wiki/Source_code_directories">CVS
+Modules</a> or top level directories (in Subversion) available from
+OpenOffice.org. </li>
+</ul>
+<a name="Build"></a>Building the source
+<ul>
+  <li> <a href="background.html">Background
+Information</a> for building OpenOffice.org </li>
+  <li> <b>Description of the Build Process</b>
+The build requirements and instructions changed between OpenOffice.org
+1.1.x, the recent OpenOffice.org versions and again for the current
+development versions:
+    <ul>
+      <li> Instructions for current <b>OpenOffice.org
+development versions</b>
+<p>For current information on how to build OOo, see the OOo Wiki:
+   <a href="http://wiki.services.openoffice.org/wiki/Documentation/Building_Guide">Building Guide</a></p></li>
+      <li> <b>Outdated</b> Instructions for <b>ancient OpenOffice.org versions (2.0.x and 3.0.x)</b><br>
+        <ul>
+          <li><a href="dev_docs/build_linux.html">Linux</a></li>
+          <li><a href="dev_docs/build_solaris.html">Solaris</a> </li>
+          <li><a
+ href="http://wiki.services.openoffice.org/wiki/Mac_OS_X_Build_Instructions">Mac
+OS X (X11)</a> or <a
+ href="http://wiki.services.openoffice.org/wiki/AquaBuild">Mac OS X
+(Aqua)</a></li>
+          <li>Windows with Microsoft Visual C++ .NET2003 Compiler<br>
+            <a href="dev_docs/build_windows_tcsh.html">with Cygwin tools</a><br>
+          </li>
+          <li>Windows with Microsoft Visual C++ 2005 Express
+Compiler&nbsp;<a
+ href="http://wiki.services.openoffice.org/wiki/Windows#Visual_C.2B.2B_Express_2005">click
+here</a></li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+  <li><a href="build_env.html">Build
+Environment</a> description ( for OpenOffice 2.x/3.x series ) </li>
+  <li> <a href="project_dependencies.png">Diagram
+of inter-project dependencies</a> by C.P. Hennessy </li>
+  <li> <a href="troubleshoot.html">Tips
+for Troubleshooting</a> the build. </li>
+</ul>
+<h4>Testing the code</h4>
+<ul>
+  <li>
+    <p><a href="http://wiki.services.openoffice.org/wiki/Tinderbox">Tinderbox</a><br>
+With many developers working on different platforms on the same
+codebase easiely leads to <emph>incompatibilities</emph>. A Tinderbox
+allows you to check the "buildability" of the current code and helps
+finding who broke the build. The Tinderbox provides the build logfiles
+so that it is easy to check what (and who) broke the build.</p>
+    <p> If you have some CPU time to burn please consider running a <a
+ href="http://wiki.services.openoffice.org/wiki/Tinderbox">tinderbox
+client</a>. We need many tinderbox client machines that are doing
+builds! </p>
+    <p> Tinderbox topics/issues can be discussed on the
+tinderbox@tools.openoffice.org <a
+ href="http://tools.openoffice.org/servlets/SummarizeList?listName=tinderbox">
+mailing list</a>. </p>
+  </li>
+</ul>
+<h4>Working on the code</h4>
+<ul>
+  <li> <a name="codinguidelines"></a> <a href="CodingGuidelines.sxw">Coding
+Guidelines</a> (.sxw) </li>
+  <li> <a href="policies/java_usage.html">Usage Of Java Policies</a> </li>
+  <li> <a href="InterfacesChecklist.sxw">Checklist for C++ Interface
+Reviews</a> (.sxw) </li>
+  <li> <a href="debugging/usingvalgrind.sxw">DebuggingOpenOffice.org
+with Valgrind</a> (.sxw) </li>
+</ul>
+<br>
+<h4>OpenOffice.org Development with child workspaces (CWS):</h4>
+<ul>
+  <li><a href="dev_docs/OOo_cws.html">Overview</a></li>
+  <li><a href="dev_docs/ooo-cws-tools-doc.sxw">Tools</a><br>
+  </li>
+  <li><a href="dev_docs/child_workspace_policies.html">Policies</a><br>
+  </li>
+  <li><a href="dev_docs/child_workspace_newmodule.html">Introduce a new
+module</a><br>
+  </li>
+</ul>
+<h3>Tools description</h3>
+<ul>
+  <li>
+    <p>Description of Autodoc (automatic
+documentation generation) <br>
+( for <a href="autodoc/HowToWriteDocumentation-Cpp.html">C++</a> and <a
+ href="http://api.openoffice.org/docs/DevelopersGuide/Appendix/IDLDocumentationGuide/IDLDocumentationGuide.xhtml">UNO-IDL</a>;<a
+ href="autodoc/CommandLineSyntax.html">commandline syntax</a>). </p>
+  </li>
+</ul>
+<h3>Performance and Profiling</h3>
+<p>Tools for performance measuring and related tasks. </p>
+<ul>
+  <li> <a href="performance/index.html">Performance Tuning and tools</a>
+  </li>
+  <li> <a href="profiling/index.html">Profiling tools</a> </li>
+</ul>
+<h3>Quality Assurance (QA)</h3>
+QA is a separate <a href="http://qa.openoffice.org">project</a>.
+<ul>
+  <li> <a href="http://qa.openoffice.org/testcase/index.html">Description</a>
+of the Smoke Test </li>
+  <li> <a
+ href="http://qa.openoffice.org/issue_handling/bug_writing_guidelines.html">Issue
+Writing Guidelines</a> </li>
+</ul>
+<h3>Release Engineering</h3>
+<ul>
+  <li> Overview of <a
+ href="http://development.openoffice.org/releases/oo_branches.pdf">Branches
+and Roadmap of
+OpenOffice.org</a> releases and <a
+ href="http://development.openoffice.org/releases/index.html">description
+of branches</a>. </li>
+  <li> <a
+ href="http://eis.services.openoffice.org/EIS2/servlet/GuestLogon"><strong>E</strong>nvironment
+    <strong>I</strong>nformation <strong>S</strong>ystem</a> is a
+Child Workspace (CWS) browsing interface</li>
+  <li> <a
+ href="http://development.openoffice.org/releases/filenames.html">File
+Naming Scheme</a> </li>
+</ul>
+<center>$Revision: 1.106 $ $Date: 2010/06/08 16:09:13 $
+</center>
+</body>
+</html>

Propchange: incubator/ooo/ooo-site/trunk/content/tools/index.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/ooo/ooo-site/trunk/content/tools/modules.gif
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/tools/modules.gif?rev=1175537&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/ooo/ooo-site/trunk/content/tools/modules.gif
------------------------------------------------------------------------------
    svn:mime-type = image/gif



Mime
View raw message