This document attempts to explain the OpenMDAO development process and how a developer should interact with the various tools the project uses for version control, testing, deployment, etc. The source files for the Developer Guide can be found in the docs/dev-guide directory in the top level of your OpenMDAO source repository.
Working with OpenMDAO as a developer has some system requirements in addition to those mentioned in the System Requirements section of the User Guide. These requirements are described below.
Certain packages used in OpenMDAO contain Python extensions, meaning that they contain non-Python source code that must be compiled. Packages currently in use require either C/C++ or Fortran compilers.
Linux:
gcc
gfortran
If they are not already on your system, they should be easily installable using your package manager. OpenMDAO currently builds and passes all tests with gcc/gfortran 4.1.2. We expect that later versions of gcc/gfortran 4.X should also work.
Mac OS X:
gcc
Is available as part of Xcode, which can be found on the OS X distribution disks but typically is not installed by default. You can also download gcc and install it from source, although this is more prone to installation problems.
gfortran
Binaries for gfortran are available here.
Windows:
Visual C++ 2008
We use the Express version, but others (Professional, Standard) should work too. To get this software, go to the downloads page.
mingw32 (for Fortran and optionally as a Visual C++ replacement)
Make sure to put the bin directory of the mingw32 install in your path. You can find mingw32 here.
If you intend to use mingw32 as a Visual C++ replacement, you must do two things when installing it:
Check the C++ compiler installation option to get g++ (required to run OpenMDAO)
Create a file in your home directory called pydistutils.cfg that contains the following lines:
[build_ext] compiler=mingw32
Some steps of the development process, e.g., downloading a branch of the source repository and downloading Python distributions, require network access. If you’re using Linux or Mac OS X and are behind an http proxy, you may have to set the http_proxy environment variable on your system for Bazaar and virtualenv to function properly. If you’re using Windows 7, please follow this link for information on configuring proxy settings.
If you have not previously used Bazaar on a particular machine where you intend to work with Bazaar repositories, you should run the whoami command so that Bazaar will know your email address. You need to supply your first and last name and your email address in the following way:
bzr whoami "Joe Cool <joe@example.com>"
This way, your contact information will be included whenever you commit to a repository on that machine.
Before you can do any development work on OpenMDAO, you’ll need a copy of the source code. The source repository for the OpenMDAO project is available on Launchpad. You can create a copy of the repository by typing:
bzr branch lp:openmdao <branch_name>
where <branch_name> is the name you are assigning the top level directory of your branch repository. It’s a good idea to name branches based on ticket numbers in our bug tracker (Trac) using the form T<ticket_number>-<desc>, where ticket_number is the Trac ticket number and <desc> is a short description of the branch, for example, T0029-workflow_fix. Trac automatically assigns a ticket number when you submit a bug or request an enhancement. You can visit the OpenMDAO website to find out more about how we use Trac and about the OpenMDAO development process.
In any case, the name you give your branch should reflect the purpose of the branch to avoid confusion if you have multiple branches active at the same time. If you do not supply a <branch_name>, the name by default will be the last part of the source repository URI, which in this case is openmdao.
After you’ve created your branch, run python go-openmdao-dev.py from the top directory of your branch to set up your development environment. (The devenv directory that is created is not part of the source repository.) The script will check the version of Python you are running. You must be running version 2.6. (To find out which Python version you are running, you can type python --version.)
Note
If you’re using Visual Studio on Windows, you need to run the installer from a command window that has the Visual Studio environment variables set. The easiest way to do this is to select the Visual Studio 2008 Command Prompt from the Visual Studio Tools menu under Microsoft Visual C++ 2008 Express Edition in the Start menu. If you’re using something other than the Express edition, then the name of the Start menu option will be slightly different, i.e., replace “Express” with “Professional” or “Standard.”
python go-openmdao-dev.py
Running go-openmdao-dev.py populates your virtual Python environment with all of the packages that OpenMDAO depends upon and installs the openmdao namespace packages in your virtual Python environment as “develop” eggs so that you can make changes to the source code and immediately see the results without having to rebuild any distributions.
The next step is to activate your virtual Python environment. Change your directory to devenv.
On Linux or Mac OS X, you must be running the Bash shell. If you are in Bash, omit this step.
bash
Next, type the following, making sure to include the ”.” in the command:
. bin/activate
Or, on Windows, type:
Scripts\activate
At this point, your devenv directory should contain the following subdirectories, unless you are on Windows. On Windows, the directory structure is slightly different, as noted below.
After your virtual Python environment has been activated, you can add other distributions to the environment by using easy_install or pip in the same manner that you would add packages to the system level Python.
If you make doc changes and need to rebuild the docs, you can run openmdao_build_docs. Running openmdao_docs will display the documents in HTML in the default browser.
You can deactivate the environment by typing:
deactivate
The directory structure of your repository should look like this:
OpenMDAO is split up into multiple Python packages, all under a top level package called openmdao. This top package, called a namespace package, is a sort of fake package that allows us to maintain and release our subpackages separately while appearing to the user to be all part of the same top level package. The following packages under the openmdao namespace have a similar directory layout: openmdao.main, openmdao.lib, openmdao.devtools, openmdao.util and openmdao.test. The layout is shown below.