Accessing and Running Source Code

Subversion

Subversion Clients

Subversion is a system that tracks and versions changes made to source code. NVDA's source is stored in a Subversion repository, so to get access to the code, you will need to get and install a Subversion client.

A nice graphical client which integrates into Windows Explorer is called TortoiseSVN. For those who would prefer a nice and simple command-line client, one can be found in the Cygwin distribution. Cygwin is a free Unix distribution of GNU programs that runs on top of Windows.

Getting the Code

The address for the trunk branch of NVDA's svn repository (which is the branch of code that most people will want to get) is: http://svn.nvda-project.org/nvda/trunk You can either check out or export the source code, though checking out has the advantage that you will be able to easily update your local copy whenever there are changes, rather than having to retrieve it from scratch.

To check out the latest revision with the command-line client you would do:

svn checkout http://svn.nvda-project.org/nvda/trunk/

You can add a -r parameter followed by a space and then the revision number if you want a particular revision. You can also specify a local directory name after the address.

Dependency Packages

The NVDA source code depends on several other packages which must be installed in order for NVDA to function. A list of these dependencies, any specific version requirements and links to their respective home pages can be found in the file dependencies.txt in the NVDA source directory.

Preparing NVDA Source

There are a few things that must be generated before NVDA can be run. These are COM interfaces, compiled language files and Python bytecode. To generate these things, please run generate.py in the source directory. (you should be able to just press enter or click on generate.py if your Python distribution has been installed correctly.)

Running NVDA

To start NVDA, run nvda.pyw in the source directory. (Pressing enter or clicking should start it.) You should hear a musical tune and NVDA should announce that it has started.

If NVDA does not start properly, you might consider reporting a bug.

Bazaar

The NVDA project is slowly transitioning to a new distributed version control system called Bazaar (bzr). Distributed version control makes it much easier for people who are not part of the NVDA core development team to contribute, as anyone can maintain their own branch of the code. Branching is extremely simple and branches can be easily merged, which allows for greater flexibility even for the core developers.

Bazaar Client

There is currently no accessible graphical Windows client for Bazaar, so the command line client (bzr) must be used. Most users will want the standalone Windows installer for the command line client available from Bazaar project files. Bzr can also be run under Cygwin.

Official NVDA Bazaar Branches

All NVDA Bazaar branches can be found at: http://bzr.nvaccess.org/nvda/ The main branch of NVDA, known as trunk in Subversion, is located at: http://bzr.nvaccess.org/nvda/main/

NVDA uses the NV Access virtual buffer library, which is also maintained in Bazaar. The main branch of this library is located here: http://bzr.nvaccess.org/virtualBufferLibrary/main/

Using bzr

You should probably read the Bazaar documentation for more information about the bzr command line client. However, here are some quick tips to get you started. Remember that you can use the bzr help command for more information.

Lightweight Checkout

If you are a user who wants to test a particular branch and you do not intend to make your own changes, you probably want a lightweight checkout. This is where you download the current revision of the code, but the server must be accessed for all version control operations. This also means you cannot commit your own code changes, as you do not have access to modify these branches.

A lightweight checkout is performed by passing the --lightweight option to the checkout command. For example, to get a lightweight checkout of the main NVDA branch, you would type:

bzr checkout --lightweight http://bzr.nvaccess.org/nvda/main/

To update this checkout, type the following while in the checkout directory:

bzr update

Making Your Own Branch

The power of distributed (or decentralised) version control systems is that everyone can have their own branch of the code. If you do want to make your own changes to the code and perhaps contribute them to the project, you should make your own branch. You do this using the branch command. For example:

bzr branch http://bzr.nvaccess.org/nvda/main/

You can make your branch mirror another branch using the pull command. You can merge other branches using the merge command.

Shared Repository

If you are going to create multiple branches of the code (which is quite likely), you should probably store them in a shared repository. A repository allows several branches to share common revision information, which saves disk space and bandwidth and makes branching faster. You can create a repository as follows:

bzr init-repo nvda

This creates a repository in the directory called nvda. Any branches created inside this directory will use this repository.