Difference between revisions of "Documentation/Building Guide/Basic Concepts"
B michaelsen (talk | contribs) (cleaned up builds sections) |
|||
| (13 intermediate revisions by 8 users not shown) | |||
| Line 1: | Line 1: | ||
| + | {{Documentation/Building Guide TOC | ||
| + | |ShowNextPage=none | ||
| + | |ShowPrevPage=none | ||
| + | }} | ||
{{DISPLAYTITLE:Basic Concepts}} | {{DISPLAYTITLE:Basic Concepts}} | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
To understand all concepts, techniques and the terminology described in this guide, make sure you understand the following basic concepts. | To understand all concepts, techniques and the terminology described in this guide, make sure you understand the following basic concepts. | ||
| Line 30: | Line 18: | ||
|} | |} | ||
| − | = Branches = | + | == Branches == |
| − | == Development branch | + | === Development branch === |
| + | |||
| + | The current development branch is located at: | ||
| + | |||
| + | http://svn.apache.org/viewvc/openoffice/trunk/ | ||
This is where most development is done. It has the most open policy for applying patches and it is typically where new features are developed and debugged. | This is where most development is done. It has the most open policy for applying patches and it is typically where new features are developed and debugged. | ||
| − | The good side to this is that you have the latest features, the down side is that you get the side effects of the changes | + | The good side to this is that you have the latest features, the down side is that you get the side effects of the changes. |
| − | |||
| − | == Stable branch | + | === Stable branch, specialized branches === |
| − | A stable branch is base for a release build of the OpenOffice | + | The latest stable release as well as branches that are used for development of some specialized aspect are located at: |
| + | |||
| + | http://svn.apache.org/viewvc/openoffice/branches/ | ||
| + | |||
| + | A stable branch is base for a release build of the OpenOffice product. This is where bug fix tracking takes place. The policy on these branches are to fix functional errors only. | ||
The good side is that any patches are more thoroughly vetted before going into a stable release. Therefore you have fewer mystery bugs. The downside is that there are fewer features and some bug fixes are already in the developer release. | The good side is that any patches are more thoroughly vetted before going into a stable release. Therefore you have fewer mystery bugs. The downside is that there are fewer features and some bug fixes are already in the developer release. | ||
| − | == Porting branch == | + | <!-- no longer used |
| + | === Porting branch === | ||
This is where a lot of porting to new platforms takes place. There are few features added in these branches and sometimes they are somewhat outdated in terms of functionality as a port needs some stability so that they are not solving new problems but working to an end goal together. | This is where a lot of porting to new platforms takes place. There are few features added in these branches and sometimes they are somewhat outdated in terms of functionality as a port needs some stability so that they are not solving new problems but working to an end goal together. | ||
| Line 52: | Line 48: | ||
This branch is used for platforms that are not yet part of the official release platforms, e.g. Irix and Linux s390. | This branch is used for platforms that are not yet part of the official release platforms, e.g. Irix and Linux s390. | ||
| + | --> | ||
| − | + | == Modules == | |
| − | = | + | The source code directory contains a lot of folders, each one representing a module. A module provides an application, a function, or simply just a collection of classes. A module is the smallest unit of the office suite that can be built. |
| − | The source code directory contains a lot of folders, each one representing a module. A module | ||
| − | |||
| − | |||
Modules correspond to the directories under the top-level directory of the source tree. For example, the Writer project includes the sw, starmath, res modules, etc. | Modules correspond to the directories under the top-level directory of the source tree. For example, the Writer project includes the sw, starmath, res modules, etc. | ||
| Line 68: | Line 62: | ||
We find that sw depends on connectivity etc. These modules in turn depend on others creating a large complex dependancy tree. | We find that sw depends on connectivity etc. These modules in turn depend on others creating a large complex dependancy tree. | ||
| − | {{ | + | {{Note|For more information on modules, see: |
* [[Source code directories]] | * [[Source code directories]] | ||
| − | * [[Module Build Order]]}} | + | * [[Module Build Order]] |
| + | * [[New Module]]}} | ||
| − | = Build Styles = | + | == Build Styles == |
| − | == | + | === Full Builds === |
| − | + | Developers typically perform a full build of OpenOffice in order to build their modules. A full build also recompiles all of the source code. It can take up to a few hours to perform a full build of OpenOffice.org even on modern workstations. However using tools such as distcc and ccache can have dramatic time improvements. | |
| − | == | + | === Partial Compatible/Incompatible Builds === |
| − | To avoid the need of a time-expensive complete re-build each time a change in the code is introduced, the developers are asked to introduce only ''binary compatible'' changes in the code unless | + | To avoid the need of a time-expensive complete re-build each time a change in the code is introduced, the developers are asked to introduce only ''binary compatible'' changes in the code unless it is agreed with the project owner. This means that the changes made are of such a nature that no recompilation of further dependent modules become necessary (inserting a new, non-virtual method in a C++ class would be an example of such a binary compatible change). The office suite will then be re-compiled as a so-called ''respin build'' before the next 'master' s declared. A respin build obeys only weak dependencies, i.e. dependencies within a module. Using weak dependencies allows you to, for example, to modify a base library header file without needing to perform a full build. Since a respin build relies on binary compatible changes, modules can be build in parallel, and the build takes much less time (a few hours) in contrast to a full build. |
| − | {{ | + | {{Note|By contrast, ''binary incompatible'' changes require a full build. For reasons of efficiency, this is allowed only with the approval of the project owner.}} |
| − | = Snapshots | + | === Snapshots Builds === |
| − | OpenOffice. | + | OpenOffice employs a buildbot for snapshot builds. However, the output of these builds are for developer use/information only. They are not advertised for public consumption -- beta testing. |
| + | We follow Apache rules for the announcement of releases. | ||
| − | = Source and Output Trees = | + | == Source and Output Trees == |
| − | OpenOffice.org developers work in parallel on all platforms. The source code for all platforms is identical, with the exception of the code for the interface to the operating and window managers. This allows you to build for the different platforms simultaneously from a single ''source tree'', i.e. the directory structure that stores all of the source code for the office suite. | + | OpenOffice.org developers work in parallel on all platforms. The source code for all platforms is identical, with the exception of the code for the interface to the operating system and window managers. This allows you to build for the different platforms simultaneously from a single ''source tree'', i.e. the directory structure that stores all of the source code for the office suite. |
The <code>solenv</code> tree contains the environment tools that the build process uses, for all supported platforms. Formerly it also included the platform-specific build tools. Now these build tools are created with a <code>bootstrap</code> script created with the <code>configure</code> script. | The <code>solenv</code> tree contains the environment tools that the build process uses, for all supported platforms. Formerly it also included the platform-specific build tools. Now these build tools are created with a <code>bootstrap</code> script created with the <code>configure</code> script. | ||
| − | The build process generates files from the ''source tree'' | + | When building multiple modules, these steps are taken for each module: |
| + | * The build process generates files from the ''source tree'' into the ''output tree'' of the module (this is a directory named after the platform, e.g. unxlngi6.pro for 32-bit Linux) | ||
| + | * After the module has been build, the results are copied to the ''solver'', a directory sitting next to the top-level modules in the <code>SRC_ROOT</code>. This step is called <code>deliver</code> (there is a tool with the same name). Modules cannot link/compile against the ''output'' directory of other modules, they only compile/link against objects in the solver. | ||
When you run <code>bootstrap</code>, the <code>solver</code> directory is created. Initially, the <code>solver</code> directory is empty. The build process populates this directory. The build process delivers all binary files, shared libraries, and dynamic link libraries to solver. | When you run <code>bootstrap</code>, the <code>solver</code> directory is created. Initially, the <code>solver</code> directory is empty. The build process populates this directory. The build process delivers all binary files, shared libraries, and dynamic link libraries to solver. | ||
| Line 98: | Line 96: | ||
When you want to build a specific project, you only need the sources of the relevant SVN modules and the output tree <code>solver</code>. You do not need the entire source tree, though typically a developer will check out one of the branches and build it from scratch. | When you want to build a specific project, you only need the sources of the relevant SVN modules and the output tree <code>solver</code>. You do not need the entire source tree, though typically a developer will check out one of the branches and build it from scratch. | ||
| − | For more information on the solenv and solver trees, see the [http://tools.openoffice.org/ Tools] project. | + | {{Note|For more information on the solenv and solver trees, see the [http://tools.openoffice.org/ Tools] project.}} |
{{PDL1}} | {{PDL1}} | ||
Latest revision as of 07:50, 7 July 2018
To understand all concepts, techniques and the terminology described in this guide, make sure you understand the following basic concepts.
Terminology
| Term | Description |
|---|---|
| SRC_ROOT | The environment variable containing the path to the directory of the source code. Example: /home/john/projects/ooo/builds/OOO310_m11 |
Branches
Development branch
The current development branch is located at:
http://svn.apache.org/viewvc/openoffice/trunk/
This is where most development is done. It has the most open policy for applying patches and it is typically where new features are developed and debugged.
The good side to this is that you have the latest features, the down side is that you get the side effects of the changes.
Stable branch, specialized branches
The latest stable release as well as branches that are used for development of some specialized aspect are located at:
http://svn.apache.org/viewvc/openoffice/branches/
A stable branch is base for a release build of the OpenOffice product. This is where bug fix tracking takes place. The policy on these branches are to fix functional errors only.
The good side is that any patches are more thoroughly vetted before going into a stable release. Therefore you have fewer mystery bugs. The downside is that there are fewer features and some bug fixes are already in the developer release.
Modules
The source code directory contains a lot of folders, each one representing a module. A module provides an application, a function, or simply just a collection of classes. A module is the smallest unit of the office suite that can be built.
Modules correspond to the directories under the top-level directory of the source tree. For example, the Writer project includes the sw, starmath, res modules, etc.
There are many dependencies between the modules, and the modules must build in a particular order. Module prerequisites are described in first line of the file prj/build.lst for example:
froddo: /data2/office/sw/prj$ cat build.lst sw sw : connectivity svx stoc uui sch NULL
We find that sw depends on connectivity etc. These modules in turn depend on others creating a large complex dependancy tree.
 |
For more information on modules, see: |
Build Styles
Full Builds
Developers typically perform a full build of OpenOffice in order to build their modules. A full build also recompiles all of the source code. It can take up to a few hours to perform a full build of OpenOffice.org even on modern workstations. However using tools such as distcc and ccache can have dramatic time improvements.
Partial Compatible/Incompatible Builds
To avoid the need of a time-expensive complete re-build each time a change in the code is introduced, the developers are asked to introduce only binary compatible changes in the code unless it is agreed with the project owner. This means that the changes made are of such a nature that no recompilation of further dependent modules become necessary (inserting a new, non-virtual method in a C++ class would be an example of such a binary compatible change). The office suite will then be re-compiled as a so-called respin build before the next 'master' s declared. A respin build obeys only weak dependencies, i.e. dependencies within a module. Using weak dependencies allows you to, for example, to modify a base library header file without needing to perform a full build. Since a respin build relies on binary compatible changes, modules can be build in parallel, and the build takes much less time (a few hours) in contrast to a full build.
|
By contrast, binary incompatible changes require a full build. For reasons of efficiency, this is allowed only with the approval of the project owner. |
Snapshots Builds
OpenOffice employs a buildbot for snapshot builds. However, the output of these builds are for developer use/information only. They are not advertised for public consumption -- beta testing. We follow Apache rules for the announcement of releases.
Source and Output Trees
OpenOffice.org developers work in parallel on all platforms. The source code for all platforms is identical, with the exception of the code for the interface to the operating system and window managers. This allows you to build for the different platforms simultaneously from a single source tree, i.e. the directory structure that stores all of the source code for the office suite.
The solenv tree contains the environment tools that the build process uses, for all supported platforms. Formerly it also included the platform-specific build tools. Now these build tools are created with a bootstrap script created with the configure script.
When building multiple modules, these steps are taken for each module:
- The build process generates files from the source tree into the output tree of the module (this is a directory named after the platform, e.g. unxlngi6.pro for 32-bit Linux)
- After the module has been build, the results are copied to the solver, a directory sitting next to the top-level modules in the
SRC_ROOT. This step is calleddeliver(there is a tool with the same name). Modules cannot link/compile against the output directory of other modules, they only compile/link against objects in the solver.
When you run bootstrap, the solver directory is created. Initially, the solver directory is empty. The build process populates this directory. The build process delivers all binary files, shared libraries, and dynamic link libraries to solver.
When you want to build a specific project, you only need the sources of the relevant SVN modules and the output tree solver. You do not need the entire source tree, though typically a developer will check out one of the branches and build it from scratch.
|
For more information on the solenv and solver trees, see the Tools project. |
| Content on this page is licensed under the Public Documentation License (PDL). |
