開發

From The Document Foundation Wiki
Jump to: navigation, search

完成您第一次的LibreOffice建置

第一次成功的建置LibreOffice是一項艱鉅的任務。您可以按照如何建置頁面上的指導完成您第一次建置。

如何參與

龐大的代碼量在一上來可能會讓您感到恐懼。代碼概況頁面會幫助您掌握各目錄和代碼庫的作用。

你可以根據從提交列表中實時追蹤開發進度(感謝cia.vc)。

回報臭蟲(錯誤)

回報臭蟲(錯誤)並確認臭蟲(錯誤)的存在對LibreOffice 專案來說是個寶貴的貢獻。這裡有如何回報臭蟲的資訊。

尋找問題並解決

現在已有收集Easy Hacks的名單來幫住您找到第一項任務,當然,臭蟲追蹤器有open issues中有些被標記EasyHacks以便讓您查詢。並且還有很多人開始去編譯的crazy ideas名單。

我們有設立一個專門的頁面用於收集用戶們所提供的改善建議,這個頁面在此Default UI Improvements
A page to collect ideas for improvements to the default user experience, has been started on Default UI Improvements.

Features entreprises would love to have

Another interesting feature list is related to the special needs of large corporations, where IT management has some challenges in deployment and support. We listed in this page what enterprises have already told us they love to have in LibreOffice. If you want your boss happy, help us to fix these!

Preparing patches

First of all, it would make sense to follow the OpenOffice.org Coding Style and general code conventions (such as variable naming schemes, etc). To prepare a patch that you can send to the developer mailing list, let us assume you started with a unmodified master branch. The steps are as follows:

  • Hack the code to your hearts content (if you plan something bigger, consider using feature branches)
  • Commit your changes locally to git. The first option adds all modified file, while the second option allows you to select which files become of the commit:
git commit -a

 ... or ...

git add <file1> <file2> ...
git commit

When you type a commit message, use the first line as a concise summary of your changes. The 2nd line remains empty and starting on the 3rd line you can explain how and what changes have been made for what reasons.

  • create the patch file that you want to mail. If you are in one repository you can use git directly to get e.g. the last change in your branch as a diff file with:
git format-patch HEAD~1

If you have made more wide sweeping changes across multiple repositories you can get those patches for all those repositories in one go with:

./g format-patch --suffix=.@REPO@.patch -o/home/me/somedir/to_save_my_patches_in origin/master..HEAD
  • create a mail to the development list and attach those patch files to your email.

Alternative: Offer git branches to pull from

LibreOffice being developed using git means of course that we can use all the wonderful features that git offers. E.g. people can prepare a cloned git branch that committers can pull patches from. If you plan to do that, it might be wise to coordinate with a committer in advance whether he feels comfortable in doing so.

Using Git for LibreOffice development

Git is a Distributed Version Control System (DVCS). It is a very powerful yet simple system, but if you are unfamiliar with DVCS, it can be confusing. Thankfully there are great resources on the Web to learn about Git. If you are not familiar with it, you should visit http://git-scm.com/ . The rest of this article will assume a basic working knowledge of Git.

Due to the large size of the project, the LibreOffice source code is spread among 19 distinct Git repositories. This creates new challenges even for avid git users.

./bin/g

One of the main challenges is that you will often find yourself in need to run the same git command on all the 19 repositories. The root repository contains a little utility named g, located in ./bin/g (path are given relative to your root LibreOffice git repository), or in ./g if you are using the bootstrap version.

Most commands that you would type as git xxxx, can be typed as ./bin/g xxxx which means 'run git xxxx on each repository contained in ./clone/'.

By default, for most git commands, if an error occurs executing the command in any of LibreOffice's git repositories, ./bin/g will stop and not apply the command on the rest of the repositories. To over-ride this behavior you can type ./bin/g -f xxxx.

If you're using the bootstrap version, you can simply replace all instances of ./bin/g with ./g, and everything above still holds.

Simplifying ./bin/g usage

./bin/g is normally not in your PATH. You could, of course, put it in your PATH, but that would prevent you from having multiple copies of the code base. Due to the time it takes to do a full clean build, I prefer having a second copy of the repositories, where I do mostly fresh make out of the development tip.

./bin/g not being in your PATH, makes typing the command cumbersome and error prone. The following little script - which is to be put in a directory that is in your PATH, under the name find-lo-bin - provides a solution for this problem:

#!/bin/bash

current_dir=`pwd`
while [ ${current_dir} != "/" -a -d "${current_dir}" -a ! -d "${current_dir}/.git" ] ;
do
current_dir=$(dirname "${current_dir}")
done
if [ $(basename $(dirname ${current_dir})) = "clone" ] ; then
current_dir=$(dirname $(dirname "${current_dir}"))
fi
echo "${current_dir}/bin"
unset current_dir

Now you can add this to your alias list (in your .bashrc for example):

alias g='$(find-lo-bin)/g'

With that in place, you can now just type 'g xxxx' as long as you are in a directory somewhere inside of the root LibreOffice repository.

Another limitation of ./bin/g is that it applies only to the git repositories in ./clone/ and not on the root git repository itself. More often than not, you will find yourself typing git xxx && ./bin/g xxx.

The following little script, called 'ga' provides a wrapper for just that:

#!/bin/bash

cd $(find-lo-bin)/..
if [ "$1" = "-f" ] ; then
shift
git "$@"
./bin/g -f "$@"
else
git "$@" && ./bin/g "$@"
fi
cd - > /dev/null

Grepping

You can use git grep instead of grep as it is much faster on large source trees by only looking at the files under revision control. And you can use g grep or ga grep to search on all the git repositories at once.

Another alternative is to use the opengrok web-based tool, which may be much faster than searching on your own machine.

Managing git branches

Check the current branches

To see which branch your repositories currently are on, issue:

~/loroot $ ./g branch

This lists the local branch for each repository and put a '*' in front of the one currently active. Every repository should report the same branch as active.

Adding -r after the branch command will show you the branches that are available on the remote repositores (e.g. the list of available feature branches).

Switch to a feature branch

Let's create a new feature branch 'feature/slicebread' on all git repositories based on origin/master, which allows you to safely develop a new feature:

~/loroot $ ./g checkout -b feature/slicebread origin/master

If you display again the active branch, all repositories should report 'feature/slicebread'.

If you want to switch to an existing feature branch, rather than creating a new one, do:

~/loroot $ ./g -f checkout -b feature/slicebread origin/feature/slicebread

This will create a local branch 'feature/slicebread' which tracks the remote branch feature/slicebread. The -f forces bin/g to go through all repositories without aborting, even if some repositories don't have the branch.

Going back: If you ever want to go back to master and delete your local branch, make sure you don't have any uncommited changes in your repositories, then first go back to master, and then delete your local branchfeature/slicebread.

~/loroot $ ./g checkout master
~/loroot $ ./g -f branch -D feature/slicebread

Hack and commit on a feature branch

Now you can hack and compile as you wish. Do not be shy about commiting your work. These commits are purely local and will not be visible until you publish them. You can always re-organize or fuse some commit later if you want to present a cleaner history. Each commit should contain a set of changes that are related to each other and be described clearly in the commit-log message. The first line of the commit-log message must be a concise (80 chars or less) summary of the change, then skip a line and enter a more detailed description as-needed.

Now you have implemented your new feature or you have made some progress and want to get some feedback.

First, since the master branch has probably changed since you branched-out your feature branch, you should rebase your changes, so that they apply to the most current master's HEAD.

To rebase, you need to make sure that you have committed everything that matters and clean-up your repository so that there are no changes 'pending'. Then return to the master branch with:

~/loroot $ ./g checkout master

Refresh your master branch

~/loroot $ ./g pull -r

Go back to your feature branch

~/loroot $ ./g checkout feature/slicebread

and rebase

~/loroot $ ./g rebase origin/master

If there are conflicts you need to resolve them manually and continue rebasing until you're done.

Now, it's time to publish. There are two cases.

If you do not have a set of git repositories to push these changes to, then you want to prepare a set of patches to be able to post them on the Dev-List for review.

~/loroot $ ./g format-patch --suffix=-@REPO@.patch --output-dir=<where_you_want> master..HEAD

This will generate a file per commit suffiexed by the repo name, in the directory you specified. You can then attach them to an email to the mailing list.

If you have the ability to push to a set of git repository, then

~/loroot $ ./g push origin feature/slicebread

There are plenty of excellent tutorials, books and even videos on how to use git. You are strongly encouraged to look into them. The LibreOffice Development Environment has 20 git repositories that are logically one but need to be cared for individually (hence the g and ga script).

Hack and commit on a stable branch

Stable branches are created from master or another stable branches to stabilize the code base for the release and further maintenance updates. There are just some rules during the beta phase:

  • allowed any bug fixes
  • allowed late features that are approved by Steering Committee
  • allowed any changes in translations

There are more strict rules during the release candidate phase:

  • allowed save fixes that are reviewed by another person, see below
  • allowed changes in translations; it is recommended to ask for review on the native l10n mailing list

Please, do not commit the fixes directly during the RC phase. Instead, please, ask another developer for review on the libreoffice@lists.freedesktop.orgJean mailing list, personal mail, on irc or via the related bug entry. The fix should be commited by the reviewer using:

git commit -s --author='Author name <author@mail.address>'


Reset your modified repo to a pristine "vanilla" repository

~/loroot $ bin/g reset --hard origin/master

will discard all your local changes (whether committed or not) and reset the current branch that you are on to the one on the remote repository.

Getting and using commit access

In order to get commit access you need to be "sponsored". Once you've submitted patches and got yourself recognised this won't be a problem, but it's best to wait until you're asked. Once you've been asked (or asked for someone to sponsor you), you need to get an account

General Programming Guidelines

sal_Bool should be used onlywhen it comes to UNO, and bool is preferred otherwise.

Working on specific sections of libreoffice

automake/configure

As currently implemented, there are two main configure.in files, one in the top-level build directory, and one in the libreoffice sub-directory. Any important changes should be made to both, as the top-level one is slated for removal once all the patch-sets currently in the system have been merged into the main code base.

The default arguments into the build system are currently in <loroot>/build/distro-configs.

Current configure options of the sub-level configure.in and also which options are top-level present only.

Hacking configure.in

Debugging

Development / Hacking Notes

TODO: add syntaxhighlight