Apache OpenOffice Wiki - User contributions [en]

Cpp Coding Standards/HEADERS

2006-12-15T16:33:42Z

KaiB: /* Internal Include Guards (IncGuards) */

Topic-Id: '''HEADERS'''

What to do or do not with header files.
----
=== Summary ===

==== Self Sufficient and Minimal (Self) ====

When included a header file should be self sufficient and minimal.
* Include definitions for superclasses and data members
* Create forward declarations for everything else
* Include the definition as late as possible, this helps reduce physical dependencies

// Foo.hxx
// Superclass and data member
#include "Super.hxx"
#include "Data.hxx"

// Forward declarations
class Param;

// This does not need a class definition
Param doSomething1(Param aParam);

class Foo : public Super
{
public:
// This does not need a class definition either
Param doSomething(Param aParam);

private:
Data mData;
};

// Anotherfile.cxx
#include "Foo.hxx"
#include "Param.hxx" // Now we need the definition

...
Param p;
p = doSomething1(p); // Error without the definition

==== Include Directly (IncDirect) ====
Include the header files for all types you need directly, not via another file.

==== Precompiled headers (IncPCH) ====

* The statement in each cxx files should be the inclusion of precompiled headers. There must be no other includes, no definitions and no include guards around the include statement. Forget this for a new file and you break the build.
* Assume the precompiled header file is empty and include all your headers normally.

#include "precompiled_foo.hxx" // May or may not contain includes for Foo.hxx and Bar.hxx

#include "Foo.hxx"
#include "Bar.hxx"

==== Internal Include Guards (IncGuards) ====
Internal include guards are good but '''don't''' use the external ones. They add a lot of noise for a non-existent benefit.

// Foo.hxx

// Yes, use internal include guards
#ifndef _FOO_HXX
#define _FOO_HXX

// No include guards here
#include "Superclass.hxx"
...

#endif

// Bar.cxx

// No include guards here
#include "Bar.hxx"
#include "Foo.hxx"
#include "Baz.hxx"

----
[[Category:Coding Standards]]

Cpp Coding Standards/HEADERS

2006-12-15T16:31:10Z

KaiB:

2006-10-11T17:02:12Z

KaiB: /* Updating the vendor branch */

== Updating the vendor branch ==

# Check out the unhack tools: [https://ooo.googlecode.com/svn/contrib/unhack /contrib/unhack]
# ./import-ooo-cvs <milestone> <svn_username> <svn_password>, (example: ./import-ooo-cvs m187 kai.backman secret)
# cd ~/trunk (SVN /trunk)
# svnmerge merge
# full build, resolve conflicts, repeat until no conflicts
# svn ci ~/trunk -m "Merged upstreams milestone <milestone>"

'''NB: Look into how to generate localize.sdf files in some sane manner'''

UnHackCvsSync

2006-10-11T17:02:00Z

KaiB:

2006-09-27T10:27:46Z

KaiB: /* Dashboard */

''We deconstruct OpenOffice.org''

== Dashboard ==

* Status: Sprint 1, 02-Oct to 13-Oct '''(planning)'''
* Sprint Backlog
* Burndown chart
* [http://spreadsheets.google.com/ccc?key=piRs4DLO2nrcwvgKvL74NbQ Product Backlog]

* IRC: #unhack-oo at [freenode.net]
* Mailinglist: unhack-oo@googlegroups.com

Daily Scrum Meetings:
* Scrum 1: 10.00 CET
* Scrum 2: 17.00 CET 08.00 PST

== How do I join the team? ==

You only need to commit to one 2 week sprint at a time. The Team is open to both hobbyist and professional developers of any alignment. There are only two requirements, but both are mandatory:
# Look at your calendar and find a 2 week sprint where you can commit at least 20 hours (10h per week) of work
# You need to attend at least one Scrum per day. '''Attending daily Scrums is vital.'''. The meetings usually take less than ten minutes.

Those who are part of the team are called pigs, everyone else is a chicken: [http://wiki.scrums.org/index.cgi?PigsAndChickens Pigs and Chickens].

== Process ==

The UnHack movement is operated using Scrum, a lightweight agile process. We use 2 week sprints (iterations) and two daily Scrums to account for time zone differences. The following two links have more information about Scrum:

* [http://www.controlchaos.com/about/ ControlChaos]
* [http://www.scrumalliance.org/index.php/scrum_alliance/for_everyone/what_is_scrum ScrumAlliance]

2006-08-15T11:02:57Z

KaiB:

HowToCWS

2006-08-15T10:50:28Z

KaiB:

Hacking

2006-07-14T09:29:18Z

KaiB: /* prj/d.lst */

== My first hack ==

So - we've built and run OO.o, and we want to prove to ourselves that it is in fact possible to hack on it. So in a new terminal do this:

cd build/src680-m66
. ./LinuxIntelEnv.Set.sh
cd vcl

Now have a hack at vcl/source/window/menu.cxx (Menu::SetItemText);
(near line 1770) I suggest manually applying this change:

- pData->aText = rStr;
+ pData->aText = String(rStr).Reverse();

Then save. ( You can find more sensible things to hack in the [[Tutorials]] )

You're still in vcl/ yes ? then type 'build debug=true'; wait for the scrolling text to stop; (5 seconds?). Now re-run
<code>soffice -writer</code>. You should notice the effect in the menus.
If not, ensure the previous soffice.bin was dead with
<code>killall -9 soffice.bin</code>

'''Note:''' for day to day hacking you want to just run 'build' inside the source tree. It is also highly recommended to work inside a copy of the build tree, and generate / test patches in an un-hacked version. To copy just the build/src680-m66 directory elsewhere, you need to use the [[ relocate ]] tool.

== Read the Fine manual ==

With the power of C++ comes the ability to shoot yourself in the foot all the more easily; (and implicitly), cf. Holub, Rules for C and C++ programming, McGraw-Hill, 95.


The best way to prepare yourself for battle is to read the
[http://tools.openoffice.org/CodingGuidelines.sxw OpenOffice coding guidelines], and for the easily confused c'tor / d'tor is short for
constructor / destructor.


== Sending patches ==


It is seldom clear which module a patch resides in in bugzilla.
A quick way to try and work this out is to do:
<code>cvs status <somefile> | head</code>

This should give a 'Repository Revision:' line, with a path, the
2nd fragment of this is the project name,
<code>ooo-build/bin/owner</code> automates that process for you.


In addition, since the mapping of module names to IssueZilla
tickets is rather contorted & un-documented, if you know
what module the bug is in, use [http://go-ooo.org/bug.html http://go-ooo.org/bug.html]
page to file it.


== Starting the right app ==

As you start soffice.bin, there are several useful parameters to
use to accelerate your debugging experience; particularly
<code>-writer</code>, <code>-calc</code>, <code>-draw</code>,
and (the wizardly painful) <code>-impress</code> arguments.


== Understanding D' make (man) ==

While the build system is in similar to many other systems, it is also perhaps slightly different. The overview is that each module is built, and then the results are delivered into the [http://www.openoffice.org/dev_docs/source/solver.html solver]. Each module builds against the headers in the solver. Thus there are a few intricacies.

<ul>

<li id="build">
build — this perl script solenv/bin/build.pl is
used in conjunction with [[Hacking#prj/build.lst|prj/build.lst]]
to ensure that every module that is needed is built first. 
build then un-winds internal module dependencies, and builds
each module with a chdir, dmake pair.
</li>

<li id="deliver">
deliver — this perl script solenv/bin/deliver.pl
installs headers, and libraries (etc.) into the solver, as
informed by [[Hacking#prj/d.lst|prj/d.lst]]. Crucially
deliver ensures that the date stamp on any file that is
installed to the solver is the same as that in the module's
directory. This ensures, that (particularly for headers) that
there is no dependency cascade triggering re-builds in other
modules.
</li>
</ul>

=== Standard directories ===

There are various standard directories and files in most of the modules that make up OO.o, here are some of the more useful:

*'''prj'''
**''build.lst'' — this lists directories to be made, '^#' comments are allowed, the order of the list is immaterial see [[Hacking#prj/build.lst | detail]], it is dictates ''build'''s operation.
**''d.lst'' — this file describes the ''deliver'' process, see [[Hacking#prj/d.lst | detail]].
*'''util''' — typically the util directory is charged with glueing together the sub-libraries for each sub-module into a single large library, adding system library dependencies, building GUI resource files etc. All the work is described in ''makefile.mk'', this is usually the last directory to be built in a project.
*'''inc''' — public headers are typically separated into an 'inc' directory, these will be installed into the solver by the 'deliver' phase (using [[Hacking#prj/d.lst | prj/d.lst]])

Build's mode of operation is to invoke 'dmake' in each of the projects' directories with a given dependency order. dmake then executes the rules in makefile.mk.

=== prj/build.lst ===

On first view build.lst looks scary:
<pre>
vc vcl : NAS:nas FREETYPE:freetype psprint rsc sot ucbhelper unotools sysui NULL
vc vcl usr1 - all vc_mkout NULL
vc vcl\source\unotypes nmake - all vc_unot NULL
vc vcl\source\glyphs nmake - all vc_glyphs vc_unot NULL
...
vc vcl\mac\source\src nmake - m vc__srcm vc_unot NULL
vc vcl\util nmake - all vc_util vc__plug.u vc__appa.u vc__appm.m vc__appu.u vc__appw.w vc__gdim.m vc__gdiu.u vc__gdiw.w vc__srcm.m vc__srcu.u vc__srcw.w vc__wina.u vc__winm.m vc__winu.u vc__winw.w vc__du.u vc__gtka.u vc__gtkw.u vc__gtkg.u vc__kde.u vc_app vc_ctrl vc_gdi vc_hlp vc_src vc_win vc_glyphs NULL
</pre>
so we need to try and un-pack what's going on here, which is in fact not
as odd as it might seem at first glance. Firstly lists are terminated
by the 'NULL' string. Every line is prefixed by a shortcut which has to be unique, no two modules are allowed to have the same shortcut.

<ul>
<li>
First active line contains a ':', this describes the
fact that this project (vcl) depends on these other modules
'nas', 'freetype', 'psprint' etc. to be built first. This is
for inter-project dependencies.
</li>
<li>
Some modules have a CAPITALS:lowercase arrangement; the first
segment is a conditional, driven by a space delimited list in
the BUILD_TYPE environment variable at build time.
</li>
<li>
Then we have a redundant line 'usr1' [ for fun ? ], in fact
only lines containing the magic string 'nmake' are valid after
this.
</li>

<li>
The next lines describe internal project directory dependencies
and look like:
<pre>
[shortcut] [path to dir to build] nmake - [flags] [unique-name] [deps...] NULL
vc vcl\source\glyphs nmake - all vc_glyphs vc_unot NULL
</pre>
shortcut is not used; flags determines which platforms
this builds on; usually single char platform codes: 'dnpum' 'u' being
Unix. The higher up the system, the more stuff is flagged 'all'. 
unique-name this is a magic name, used by other lines to
describe an internal dependency. deps... any number of names of
other directories in this file, that must be built before this one. If such prerequisite dir is built for special platforms only, the platform code has to be appended to its magic name.
</li>

</ul>

So we see in the vcl case that vcl\source\unotypes (vc_unot) has to be built before vcl\source\glyphs (vc_glyphs). For Mac vcl\mac\source\src (vc__srcm) has to be built before vcl\util (vc_util) It is '''important''' to understand that the order of the list is ~immaterial, and instead of a simple ordered list, we have a more complex internal dependency system — this contrasts with most other make systems.

There is also documentation [http://tools.openoffice.org/tools/build.html here] on it.

=== deliver, deliver.log and prj/d.lst ===


The syntax of d.lst is more comprehensible than build.lst, it omits
some default actions, such as copying build.lst into
inc/<module>/build.lst.

A line is of the form:
<pre>
[action]: [arguments]
mkdir: %_DEST%\inc%_EXT%\external
</pre>
where if '[action]:' is omitted, it defaults to the 'copy' action. Typical actions are copy, mkdir, touch, hedabu, dos and linklib.

The 'hedabu' action is particularly interesting, inasmuch that it
cosmetically re-formats the header to shrink it on install and adds the module name to the include path (''#include "my_header.hxx"'' becomes ''#include <my_module/my_header.hxx>''). Otherwise
it's much like the copy action.


During the action, various macro variables are expanded some of which are:
<ul>
<li>%__SRC% — distribution directory name eg. unxlngi4.pro</li>
<li>
%_DEST% — absolute path into solver eg.
/opt/OpenOffice/OOO_STABLE_1/solver/641/unxlngi4.pro

</li>
<li>
%_EXT% — (unusual) way of having minor updates eg. 641.1,
typically used to version every base sub-directory.
</li>
</ul>
Typically then, if indeed you need to add a rule (cf. implicit directory copies), it will be of the form:
<pre>
..\%__SRC%\inc\sal\*.h %_DEST%\inc%_EXT%\sal\*.h
</pre>
NB. relative paths are relative to the 'prj/' directory.


Sometimes you might run into the situation where you'd like to remove the delivered files from solver. Your configuration might have changed and they are no longer needed. "deliver -delete" does just that, however you might still need to delete "deliver.log" files manually as well.

== Can I get a <code>char *</code>, please? ==


Just barely. OO.o has at least six string wrappers, although the C
implementations are of little interest:


<ul>
<li>


<code>rtl_String</code> — sal/inc/rtl/string.h 
"Normal" string plus reference counting.
<code>rtlstring-</code>><code>buffer</code> is useful, as is
<code>rtlstring-</code>><code>length</code>. This object encapsulates
an generic 8bit string - of unknown encoding. Feel free to treat
<code>rtlstring-</code>><code>buffer</code> as your beloved <code>char *</code>.
If you really want to look at the implementation of some
<code>rtl_String</code> function and lxr nor grep can help you, have
a look at sal/rtl/source/strtmpl.c.


</li>

<li>

<code>OString</code> — sal/inc/rtl/string.hxx 
Simply a rtl_String wrapped inside a <code>class</code>; you
can use <code>ostring.pData</code> to get at the rtl_String
(it's public). <code>OString</code> has reasonably useful
methods for if you need them.


</li>

<li>

<code>rtl_uString</code> — sal/inc/rtl/ustring.h 
"Normal" Unicode string, similar to rtl_String, and
refcounted as well. However, this one always comes in UCS-2
encoding, presumably to be compatible with Java's
questionable choices.
See <code>rtl_String</code> above to find where the implementation
of some <code>rtl_uString</code>functions is hidden.


</li>

<li>

<code>OUString</code> — sal/inc/rtl/ustring.hxx 
An rtl_uString wrapped inside a <code>class</code>. This is
what most of the OO.o code uses to pass strings around.
To convert an <code>OString</code> to an <code>OUString</code>

it is necessary to specify the character set of the
<code>OString</code> see; <code>sal/inc/rtl/textenc.h</code>
— the only interesting case is <code>RTL_TEXTENCODING_UTF8</code>

</li>

<li>

<code>String</code> — tools/inc/string.hxx 
This is an obsolete string class, aliased to 'UniString'.
It has a number of limitations such as a 64k length limit.

</li>
</ul>

A couple of conversion functions are really useful here, particularly: 
<code>rtl::OString aOString = ::rtl::OUStringToOString (aOUString, RTL_TEXTENCODING_UTF8);</code>
 And the reverse: 
<code>rtl::OUString aOUString = ::rtl::OStringToOUString (aOString, RTL_TEXTENCODING_UTF8);</code>

If you just want to programattically print out a string for debugging purposes you probably want define a macro like : 
<code>#define CHAR_POINTER(THE_OUSTRING) ::rtl::OUStringToOString (THE_OUSTRING, RTL_TEXTENCODING_UTF8).pData->buffer</code>
 and use it like : 
<code>printf ( "SvXMLNamespaceMap::AddIfKnown : %s / %s\n", CHAR_POINTER(rPrefix), CHAR_POINTER(rName) );</code>.
 In ooo-build you can use stream operator<< to dump OUString easily for debugging purposes; like <code>std::cerr << "The string is: " << aOUString << std::endl;</code>.

To print the value of rtl::OUString directly in the debugger, you can use <code>dbg_dump()</code>. It is intended to be called interactively from the debugger, in both debug and non-debug builds of OOo. You can see the definition in sal/rtl/source/debugprint.cxx.

Some code snippets about manipulating those objects can be found on the codesnippets service page : [http://codesnippets.services.openoffice.org/Office/cpp.xml]

== Linkoo & Limitations ==

Linkoo is the tool that implements the <code>-l</code>
functionality of <tt>[[bin/ooinstall]]</tt>. It essentially
sym-links files of similar names into your local tree,
allowing a fast development iteration.


It is however slightly limited - some of the modules
cannot be linked for various reasons; these are:
<code>cppuhelper</code> and <code>configmgr</code>,
thus in the rare case that these are altered, they
must be copied manually into <code>/opt/OOInstall/program</code>.


In addition symlinks cannot be used for soffice.bin, and this is more commonly altered - it has to be installed from <code>desktop/unxlngi4.pro/bin/soffice</code> NB. with an appended '.bin'

== See also ==

*[[Debugging]]

[[Category:Development]]

CPAN install

2006-07-04T15:40:06Z

KaiB: /* Troubleshooting */

=Short guide for CPAN downloads=
As you might need to install additional perl modules to build OOo 2.0 or to use the tinderbox script this document describes briefly how to access and use CPAN.

==What is CPAN?==
CPAN is the Comprehensive Perl Archive Network, a large collection of Perl software and documentation. You can begin exploring from either http://www.cpan.org/, http://www.perl.com/CPAN/ or any of the mirrors listed at http://www.cpan.org/SITES.html and http://mirror.cpan.org/.

Note that CPAN is also the name of a Perl module, CPAN.pm, which is used to download and install Perl software from the CPAN archive.

This page tells you only enough to use this Perl module to install additional perl modules. You may find the documentation for it by using perldoc CPAN via the command line or on the web at http://search.cpan.org/author/JHI/perl-5.8.0/lib/CPAN.pm.

==Install a module with CPAN.==

If you are behind a firewall set FTP_PASSIVE to 1.

$ export FTP_PASSIVE="1"

Start the CPAN module.

$ perl -MCPAN -e shell

If this is your first time you use this module you have to answer some questions of this module. Just follow the directions on your screen.

For example, if you want to install the Mail::Sender module do it like:

cpan> install Mail::Sender

Typing help gets you some online help.

cpan> help

And typing quit quits the module.

cpan> quit

This is everything you need to know to use the CPAN module.

== Detailed installation instructions ==

Especially on win32 there are some issues with Crypt::SSLeay. '''CPAN''' designates modules that can be installed using CPAN directly, '''MANUAL''' indicate modules that ''must'' be installed manually (really!). The installation order is also important. Phase 1 must be installed before Phase 2 (and the internal order is significant)

Phase 1: Everyone
# '''CPAN:''' perl -MCPAN -e 'install Archive::Zip'
# '''CPAN:''' perl -MCPAN -e 'install XML::Parser'

Phase 2: For committers
# '''MANUAL:''' Crypt::SSLeay. The CPAN installation is broken.
## Download and unpack the installation tarball: http://www.perl.com/CPAN/modules/by-module/Crypt/Crypt-SSLeay-0.51.tar.gz
## Apply this patch: [http://www.openoffice.org/nonav/issues/showattachment.cgi/37505/ssleay_fix.patch ssleay.patch] (the rationale for the patch can be found [http://rt.cpan.org/Public/Bug/Display.html?id=16735 here])
## perl Makefile.PL
## make; make test; make install
# '''CPAN:''' perl -MCPAN -e 'install LWP::UserAgent'
# '''CPAN:''' perl -MCPAN -e 'install SOAP::Lite'

==Troubleshooting==

'''Problem:''' Win32/Cygwin: /bin/sh: -c: line 0: unexpected EOF while looking for matching `"'

'''Solution:''' Either your LIB or INCLUDE environment variable ends with a trailing "\" (backslash). This backslash espaces a double quote used by certain makefiles to protect variables passed to the shell. The shell then can't find the matching double quote and dies. This happens notably with SOAP::Lite and other CWS cpan modules.

'''Note:''' OOo build doesn't need LIB or INCLUDE to be set, so you can safely unset them as well.

CPAN install

2006-07-04T14:46:40Z

KaiB: /* Detailed installation instructions */

=Short guide for CPAN downloads=
As you might need to install additional perl modules to build OOo 2.0 or to use the tinderbox script this document describes briefly how to access and use CPAN.

==What is CPAN?==
CPAN is the Comprehensive Perl Archive Network, a large collection of Perl software and documentation. You can begin exploring from either http://www.cpan.org/, http://www.perl.com/CPAN/ or any of the mirrors listed at http://www.cpan.org/SITES.html and http://mirror.cpan.org/.

Note that CPAN is also the name of a Perl module, CPAN.pm, which is used to download and install Perl software from the CPAN archive.

This page tells you only enough to use this Perl module to install additional perl modules. You may find the documentation for it by using perldoc CPAN via the command line or on the web at http://search.cpan.org/author/JHI/perl-5.8.0/lib/CPAN.pm.

==Install a module with CPAN.==

If you are behind a firewall set FTP_PASSIVE to 1.

$ export FTP_PASSIVE="1"

Start the CPAN module.

$ perl -MCPAN -e shell

If this is your first time you use this module you have to answer some questions of this module. Just follow the directions on your screen.

For example, if you want to install the Mail::Sender module do it like:

cpan> install Mail::Sender

Typing help gets you some online help.

cpan> help

And typing quit quits the module.

cpan> quit

This is everything you need to know to use the CPAN module.

== Detailed installation instructions ==

Especially on win32 there are some issues with Crypt::SSLeay. '''CPAN''' designates modules that can be installed using CPAN directly, '''MANUAL''' indicate modules that ''must'' be installed manually (really!). The installation order is also important. Phase 1 must be installed before Phase 2 (and the internal order is significant)

Phase 1: Everyone
# '''CPAN:''' perl -MCPAN -e 'install Archive::Zip'
# '''CPAN:''' perl -MCPAN -e 'install XML::Parser'

Phase 2: For committers
# '''MANUAL:''' Crypt::SSLeay. The CPAN installation is broken.
## Download and unpack the installation tarball: http://www.perl.com/CPAN/modules/by-module/Crypt/Crypt-SSLeay-0.51.tar.gz
## Apply this patch: [http://www.openoffice.org/nonav/issues/showattachment.cgi/37505/ssleay_fix.patch ssleay.patch] (the rationale for the patch can be found [http://rt.cpan.org/Public/Bug/Display.html?id=16735 here])
## perl Makefile.PL
## make; make test; make install
# '''CPAN:''' perl -MCPAN -e 'install LWP::UserAgent'
# '''CPAN:''' perl -MCPAN -e 'install SOAP::Lite'

==Troubleshooting==

'''Problem:''' Win32/Cygwin: /bin/sh: -c: line 0: unexpected EOF while looking for matching `"'

'''Solution:''' Either your LIB or INCLUDE environment variable ends with a trailing "\" (backslash). This backslash espaces a double quote used by certain makefiles to protect variables passed to the shell. The shell then can't find the matching double quote and dies. This happens notably with SOAP::Lite and other CWS cpan modules.

'''Note:''' If you really have the environment variables LIB and INCLUDE set better consider yourself a wizard that is able to deal with CPAN (compiling cygwin programs in general) problems as you are most propably mixing gcc and MSVC here. Don't set LIB and INCLUDE, the OOo build doesn't need them.