Interested in improving this site? Please check the To Do page.

Using the frontierkernel repository

We use a Subversion repository hosted at SourceForge to keep track of all changes made to the Frontier kernel source code. The purpose of this document is to provide basic instructions for working with the repository. If you have any questions about working with the repository that are not answered here, please don't hesitate to post your questions to our mailing list.

Understanding Subversion

Subversion is an open-source version control system. It stores the current version and all previous versions of the source code in a central database called the repository. You use a Subversion client to access and manipulate the repository. To start working with the repository, you first use your Subversion client to download the current copy of the source code to your machine. This is called checking out a working copy. Later, you can upload the changes you made in your working copy to the repository. This is called committing or checking in your changes to the repository. Each commit or check-in creates a new revision of the repository. Subversion also allows you to view the history of a file (using the log command), to examine the differences between revisions (using the diff command) and to find out who changed which lines in which revision of a file (using the blame command).

Subversion is a complex tool. However, it is documented extensively in Version Control with Subversion by Ben Collins-Sussman, Brian W. Fitzpatrick and C. Michael Pilato, available online for free or as a dead-tree edition from O'Reilly. Before committing changes to our repository, please take the time to read at least chapters 1 to 3 of the book if you are new to the concept of version control in general or Subversion in particular. Once you are familiar with the basics, you may want to proceed to chapter 4 about branching and merging. The later chapters of the book are mainly of interest to project administrators. If you are short on time and have worked with CVS before, Appendix A. Subversion for CVS Users explains the major differences between CVS and Subversion.

The official Subversion FAQ is another excellent source of information about Subversion, especially for troubleshooting hints. Sourceforge also maintains the SourceForge.net: Subversion document that explains the specifics of using a Subversion repository hosted on their servers.

Browsing the repository

SourceForge provides a web interface to our repository which allows you to view the content of the repository with just a web browser. The web interface also allows you to examine the differences between arbitrary revisions of the whole repository or just a single file.

Getting a Subversion client

On Mac OS X, the Subversion command-line client svn may already be installed on your machine. A stand-alone package of the svn client is available from metissian.com. The svn client is also available via the Fink and DarwinPorts package managers. If you prefer a graphical user interface, svnX or Xcode's Subversion integration may work for you.

Note: Xcode isn't currently capable of doing a checkout. You will need to have a client that can. Once you have done a checkout, Xcode works well for many routine tasks.

On Windows, binary releases of the svn command-line client are available directly from the Subversion website. If you prefer a graphical user interface, TortoiseSVN provides most Subversion commands in the Explorer context menu.

If you prefer to use the same tool on both platforms, RapidSVN provides a multi-platform graphical user interface to Subversion.

See also:

Checking out a working copy

Once you have installed a Subversion client on your machine, you are ready to check out a working copy of the kernel source code. If you are using the svn command-line client, run the following command:

svn checkout https://frontierkernel.svn.sourceforge.net/svnroot/frontierkernel/Frontier/trunk Frontier

This command will check out the Frontier/trunk directory from the repository located at the URL https://frontierkernel.svn.sourceforge.net/svnroot/frontierkernel/ into a local directory named Frontier. If you are using a graphical front-end, provide it with the same pieces of information. Read-only operations on the repository like the checkout command don't require authentication. If your client prompts you for a username or password, leave both blank.

Note: If the checkout aborts with a “secure connection truncated” error, just re-run the above command. It will start from the point where it left off during the previous run. Once the checkout is complete, run svn cleanup Frontier for good measure. — André Radke 2006/03/26 16:29

Once you have checked out a working copy, you can change directories into the top-level directory of your working copy and run subsequent svn commands from there without having to specify the path to your working copy or the URL of the repository.

If you haven't worked with the Frontier source code before, the first thing you should do at this point is to consult the README file at the top level of the Frontier directory you just checked out. It contains instructions on how to build the Frontier kernel from the source code.

See also: Initial Checkout from the Subversion book

Note: By default, the svn client uses the current timestamp for files during checkout. However, you can configure it to use the actual timestamp for when the file was last modified in the repository by setting the “use-commit-times” config option. Look for “use-commit-times” in the Configuration Options section of Chapter 7: Advanced Topics of the Subversion book.

Keeping your working copy in sync

As the developers check in their changes to the repository, your working copy will get out of sync with the most recent version of the repository. The update command of your Subversion client will get your working copy back in sync with the repository. The easiest way to run it is from the top-level directory of your working copy, i.e. from inside the Frontier directory:

svn update

The update command will retrieve all changes from the repository and merge them into your working copy. If in the meantime you have made changes to your working copy which overlap with changes retrieved from the repository, the svn client will inform you about a merging conflict. Refer to the Basic Working Cycle chapter of the Subversion book to learn how to resolve merging conflicts and how to keep track of the changes you made yourself locally.

Obtaining repository write access

All the Subversion commands described so far were read-only. Running them does not affect the state of the repository and the configuration at SourceForge lets anybody execute these commands against the repository. In other words, our repository is world-readable.

However, all commands that change the state of the repository, e.g. committing changes, require prior authentication. If you are interested in contributing your changes to the project, you first need to register a user account at SourceForge. Then contact the project admins listed on the frontierkernel project page via email and ask to be granted developer access to the repository. Please include your account name and describe your qualifications (very briefly) and the areas of the source code you would like to work on.

Once the project admins have granted you developer access, you will be able to commit your changes to the repository. You should also subscribe to the frontierkernel mailing list to coordinate with the other developers. Optionally, you can subscribe to the frontierkernel-commits mailing list that sends out a notification for each change made to the repository. These notifications include the URL to a web page for reviewing the change.

Committing your changes

Before committing your changes, run the status command to obtain a list of files that you have changed since you last updated them from the repository:

svn status

To find out how exactly you modified all these files, run the diff command:

svn diff

Once you have made certain that your changes are ready to be committed, run the commit command:

svn commit

Your Subversion client should now prompt your for a log message describing your changes. The target audience of the log message is a developer who is somewhat familiar with the kernel source code but may not be familiar with the context of your changes. The log message should serve as an introduction to your changes, to be read before a developer reviews the actual changes you made to the source code. If your changes affect a small number of functions, it is a good idea to include the function names and the names of their files in the log message. If your changes are related to a bug report or feature request submitted to our trackers on SourceForge, please include the request ID in the log message, e.g. [bug #1457286] or [feature #1074730].

However, log messages should not be needed to understand the current code. If you find yourself providing detailed explanations in the log message, consider whether your explanations should not go into a comment in the changed source file instead.

If another developer has changed a file to which you are committing a change yourself, your whole commit will fail and your Subversion client will complain about one or more files being out of date. In this case, you need to run svn update, then resolve any merging conflicts before retrying the commit.

See also: Basic Work Cycle from the Subversion book

Branching and tagging

The main line of development happens in the Frontier/trunk directory. At the same time, some features are being developed in separate branches. Please refer to Chapter 4. Branching and Merging of the Subversion book for a detailed explanation of the concept of branches and how to work with them. You can also browse the Frontier/branches directory.

To obtain a working copy of for example the SQLite branch, run the checkout command as follows:

svn checkout https://frontierkernel.svn.sourceforge.net/svnroot/frontierkernel/Frontier/branches/SQLite Frontier

Alternativel, to switch your existing working copy of Frontier/trunk to the SQLite branch without checking out a whole new working copy, run the switch command from the top level of your working copy as follows:

svn switch https://frontierkernel.svn.sourceforge.net/svnroot/frontierkernel/Frontier/branches/SQLite

We also use vendor branches to keep track of third-party libraries and our modifications to their code, e.g. browse our SQLite vendor branch.

Whenever we make a binary release of the Frontier application, we create a snapshot of the source code used to compile the application. These snapshots are created with the svn copy command in the Frontier/tags directory.

Organizing the directory layout

If you need to add files or directories to the project and are uncertain where to put them, please don't hesitate to ask for guidance on the frontierkernel mailing list.


Personal Tools