How source code is organized

The source code for the Asterisk project is located on the Digium Subversion servers and managed through Subversion.

Digium runs two Subversion servers for the Asterisk project and related projects:

svn.digium.com and origsvn.digium.com
Contains Asterisk, Zaptel, Asterisk-Addons and other related projects that Digium either holds copyright on or receives contributions via the Open Source Contributor License, found at bugs.digium.com upon signing in.
svncommunity.digium.com and origsvncommunity.digium.com
Contains other Asterisk/Zaptel related projects for which Digium has no direct involvement (support, licensing, bug tracking or otherwise).

Organization varies regarding Asterisk-related
projects, but code is typically structured by the following directories:


/branches  /* the working area; fixing bugs in existing major releases */
/tags  /* future sub-releases of major release versions. snapshots of the release branches */
/team /* branch list of developers involved in project /*
/trunk /* newest version of svn code */

The newest version of SVN code can be checked out from the /trunk.

A complete view of the project repository listing can be found on Digium's public SVN repositories at svn.digium.com and origsvn.digium.com. A community list is located at svncommunity.digium.com and origsvncommunity.digium.com.

Details on Asterisk code documentation can be found in the Asterisk Developer's Documentation.

Tools required

Operating system

Asterisk is developed and tested primarily on the GNU/Linux operating system, and is supported on every major GNU/Linux distribution. Asterisk has also been 'ported' and reportedly runs properly on other operating systems as well, including Sun Solaris, Apple's Mac OS X, and the BSD variants.

Subversion

You will need to install Subversion on your system to access the Asterisk source code.

Bug tracker

The bug tracker is where you will report and submit bug patches. Feature requests are not submitted in the issue tracker.

Community resources and support

Asterisk Developers congregate and discusses the Asterisk project on the developer's mailing list and the #asterisk-dev and #asterisk-bugs IRC channels (port 6667 at irc.freenode.net ). Feature requests are presented and discussed in these areas as well.

Where to start

Asterisk and Asterisk-related projects are maintained through Subversion. Therefore, if you are interested in developing for the Asterisk project, you will need to use Subversion (SVN) to get the most up-to-date source code.

SVN commit and setup

Although commit access is not required to check out the code from the SVN repositories or to begin development on the Asterisk project, commit access can be granted, on a case by case basis, to those who have become heavily involved and are contributing on a regular
basis such that workspace on the SVN server may be provided to you.

Note: You may skip the next section if you simply want to check out the code or develop for the Asterisk project with anonymous read-only access to the SVN servers.

For those who have been granted workspace

If you have been considered for commit access and your own workspace, please note that you will not be granted access to any projects on this server without having an electronically signed active disclaimer (the Open Source Contributor License) on file with Digium, and all code you commit to any project on this server will be covered by your signed Open Source Contributor License , without exception. The license can be signed upon logging into the bug tracker.

If you have been granted workspace on the server, you will be given an access certificate. Your access certificate can be used for both servers for any projects that you have permissions to update.

The Digium Subversion servers use Apache, Subversion, WebDAV and OpenSSL. The servers are protected using SSL server and client certificates, using 2048-bit keys. The servers are completely inaccessible without a client certificate provided by Digium, from Subversion or a web browser.

You will receive a certificate named with your 'author' name. This example will use 'jdoe' as the author name, so the certificate would be named jdoe-cert.p12. You will also need the Digium_SVN-cacert.pem file. These certificates were issued using Digium's private Certificate Authority, so your Subversion client (and browsers) will refuse to accept them until you authorize them by following the instructions below.

Your personal certificate will be protected with a passphrase; the initial passphrase will be sent to you via secure channel (of some form). It is recommended that your retain the passphrase on your certificate in case you should ever allow a copy of the certificate out of your control; however, if you are willing to keep tight control over copies of your certificate and notify us immediately should you suspect it has been obtained by anyone else, you can request a certificate without a passphrase.

Subversion will allow you to store the passphrase in its cache and/or configuration file, but we strongly suggest doing this only on systems where you have complete physical control of the machine, otherwise the security of your certificate could be compromised.

Configuring subversion

Edit the ~/.subversion/servers file
In the [global] section, add the path to the Digium_SVN-cacert.pem file to the ssl-authority-files entry, or add the entry if it does not exist. Example:
```
[global]
ssl-authority-files = /home/jdoe/.subversion/Digium_SVN-cacert.pem
```
To the [groups] section, add a line 'digium = *.digium.com' (add the [groups] section if necessary). Example:
```
[groups]
digium = *.digium.com
```
Add a new section [digium], with an entry ssl-client-cert-file with the path to your personal certificate. Example:
```
[digium]
ssl-client-cert-file = /home/jdoe/.subversion/jdoe-cert.p12
```

Now you should be able to check out, update and commit to branches that you have been granted access to. Just be sure to use https://origsvn.digium.com/svn as the base for your Subversion URLs; origsvn does not have plain HTTP access, and svn.digium.com doesn't have SSL (or writeable) access at all. If your project is on the community server, you would use https://origsvncommunity.digium.com/svn instead.

If you wish to use a browser to access ViewCVS on the SVN server (not the public mirror), you can install the certificate into your browser as well. If you install it into Firefox, be sure to click the 'This certificate can identify web sites' checkbox for the 'Digium SVN CA' entry in the Authorities tab of the certificate management window. Similar steps must be taken with other browsers.

Correcting commit log messages

If for some reason when you commit a change you don't put the proper (or complete) information into the commit log message, you can correct it. Get the revision number of the commit with the incorrect message (for example, 9915), and then:


$ svn propedit svn:log --revprop -r 9915 https://origsvn.digium.com/svn/asterisk

This will open an editor window (using $EDITOR) and let you correct your mistakes, and then commit the change. Keep in mind that these properties are unversioned, meaning once you change it, the original version is gone (except for in our backups of the repository).

Get the source

After you've obtained commit access to the SVN server, check out code from the SVN repository using the following commands:


#cd /usr/src

# svn checkout http://svn.digium.com/svn/asterisk/trunk asterisk
# svn checkout http://svn.digium.com/svn/zaptel/trunk zaptel
# svn checkout http://svn.digium.com/svn/libpri/trunk libpri

To get a snapshot from the release branch of SVN, use # svn checkout http://svn.digium.com/svn/asterisk/branches/x.x asterisk-x.x with x.x being the current release and revision number. Example:

< code>
# svn checkout http://svn.digium.com/svn/asterisk/branches/1.2 asterisk-1.2
# svn checkout http://svn.digium.com/svn/zaptel/branches/1.2 zaptel-1.2
# svn checkout http://svn.digium.com/svn/libpri/branches/1.2 libpri-1.2

An important note

You can check out the source at any level of the filesystem. This includes something like svn checkout http://svn.digium.com/svn/asterisk. However, it would be a bad idea to do so, because you will end up checking out the code for every branch and tag that exists in the asterisk repository. Make sure you are careful when checking out the code

Install

After you receive the latest code from SVN, issue the following commands as root to install Asterisk on your system:


# cd zaptel
# make clean; make install
# cd ../libpri
# make clean; make install
# cd ../asterisk
# make clean; make install

Alternatively, if you checked out the 1.2 branch, you would use the following commands:


# cd zaptel-1.2
# make clean; make install
# cd ../libpri-1.2
# make clean; make install
# cd ../asterisk-1.2
# make clean; make install

Build the source

Install the following in order to build Asterisk and/or Zaptel:

ncurses, and associated -devel
openssl, and associated -devel
zlib, and associated -devel
bison, and associated -devel (1.0.X only)

Other items of interest in the Asterisk SVN repository are:

astcc - The Asterisk Calling Card Application
asterisk-addons - An addons package, which includes MySQL support for call detail records
asterisk-sounds - Additional sounds for Asterisk
btp - The Bluetooth Presence Daemon
gastman - The Graphical Asterisk call manager
iaxyprov - The IAXy provisioning utility
gtkiaxyprov - A GUI IAXy provisioning utility written in GTK

Submitting your changes

Your development changes should be posted to the bug tracker only after reading and electronically signing the Open Source Contributor License, and reading the bug guidelines.

Janitor projects

Janitor projects offer a nice starting point to begin development for Asterisk. They are a list of identified issues within the code base that need attention.

Developer branches

If you are an Asterisk Developer with commit access to your own SVN branch, read about Developer branches and branch merging.

Getting started