Working with CloudStack Code

Where to find the cloudstack code

Source code is hosted at:

https://git-wip-us.apache.org/repos/asf/incubator-cloudstack.git

You can send in diffs of your changes to the Cloudstack development mailing list, where your diffs will be reviewed and committed to the master branch that syncs up often with the external public git branch.

The master git branch is what Apache Cloudstack developers work with. To clone this branch, you will need to do -

git clone https://git-wip-us.apache.org/repos/asf/incubator-cloudstack.git

You may want to pull a specific sub-branch of cloudstack-oss. To do this, you will need to first pull the cloudstack-oss branch using the git clone command above, and then, do -

       git checkout <sub_branch_you_want_to_pull>

For example, 3.0.1 is the sub branch that was released to the Apache Software Foundation, so you would pull this branch using -

       git checkout vpc

If you ever need to clean up temp files not tracked by git that git may complain about when pulling sub branches or changing git branches, execute the command below (but please backup any of these files if you need them since this command will wipe out any files not tracked by git!) -

       git clean -d -fx ""

NOTE: If you issue the above clean command, your build/override/ directory would be removed, so you would need to re-create it. Refer to the section "How to build the cloudstack code" below to see how to create this directory and what to put into it.

Say you wish to make changes to your local sub-branch, it is always a good idea to checkout another branch from your newly created local sub-branch.

Let's summarize all the typical steps you will need to carry out, below -

Step 1) Go to the master -

        git checkout master

Step 2) Either make your changes on this branch (for a simple bugfix patch), or, create a new local branch from master -

$ git checkout -b my-feature
Switched to a new branch 'my-feature'

Step 3) Confirm that you are on your new my-feature branch -

$ git branch
master 
* my-feature

Step 6) Make your changes to the new my-feature branch, and git commit your changes.

Step 7) Pushing your changes upstream :

           There are two cases here:

             I) pushing your changes to the master branch which you pulled:

                Case a) You made changes to the local "master" branch without creating a "my-feature" branch:

                            Just do "git push"

                Case b) You made changes to the local "my-feature" branch:

                              i) git log my-feature
                                    - get all the git commits you want to push upstream, in order bottom to top (you need to maintain the right patching order!)

                              ii) git checkout {}

                              iii) git cherry-pick <commit_number_bottom-most> .. .. .. <commit_number_top-most>

                              -- Alternately, you can do a simple -

                              ii) git checkout 3.0.x; git merge my-feature

                                    -- This will pull all your changes/commits that you made to my-feature.

                              iv) git push

             II) pushing your changes to a private branch that you forked off master:

                     Here, all steps for Case I) hold good, up until iii). But during git push, do this instead:

                              $ git push origin my-feature:pvt-my-feature

                     This will create a new branch "pvt-my-feature" on the origin (which is git.cloud.com's cloudstack-oss) and team members can pull this branch and check in all the feature code changes into it. To pull this branch, just do -

                               git checkout master
                               git checkout pvt-my-feature

Other useful git commands

git stash

  - Lets you stash away the changes if you don't want to commit them yet but want to change your branch

git stash apply

git stash drop

How to build the cloudstack code

Refer to this page for details on how to set up a build environment for cloudstack on Windows -

Setting up Cloudstack dev environment on Windows

The cloudstack git branch has an INSTALL.txt file that provides instructions on setting up a build environment for Linux, taking FC 14 as an example. However, details of the setup may vary between Linux distributions, hence please refer to the specific Linux distribution's installation/product support notes when setting up a build environment for cloudstack.

In this section, we will attempt to list cloudstack's various components, and map them to specific entry points in the Cloudstack code base. In general, viewing the code flow as occurring between a client, a mid tier, and a backend makes it easier for us to look at the code.

Refer to the Cloudstack UI page for details on Cloudstack's user interface.

Refer to the Cloudstack API page for details on Cloudstack's API layer.

Refer to the Cloustack Database page for details on Cloudstack's database layer.

Refer to the Cloudstack Error Codes and Exception handling page for details on Cloudstack's exception processing.