Developers Documentation



301 error for file:

User Tools

Site Tools

Tutorials Comprehensive Development Environment and Source

The following document is intended for the core ClearOS development team. It provides some tips and tricks on managing the full ClearFoundation source code tree, including:

  • Apps
  • Themes
  • The framework

For developing or maintaining a handful of apps, you can clone the individual apps instead of using the more complex methodology described in this document. Here are two documents that describe the simpler process:

Webconfig Super-project

The source code for the ClearFoundation apps, themes and framework have been organized under the Webconfig super-project using git submodules. You can browse the submodule structure here.

By convention, the documentation will place the ClearFoundation source in ~/clearos, while personal app development will go under ~/github_account. You can put the source code wherever you want as long as the .clearos configuration file contains the paths.

SSH Access Only

Git access is done via SSH, so don't forget to ssh -A into your development environment.


To clone the entire Webconfig super-project, run:

git clone --recursive clearos
cd clearos
git submodule foreach git checkout master

The second git command is important. When the super-project is cloned, the individual projects are not set to a particular branch. You will end up in limbo if a branch is not set.


Keeping your development area up-to-date is a good practice. To update all the projects in the super-project, run:

git submodule foreach git pull

Pulling New Submodules

If a new submodule is added to the super-project, it will not appear in your local git automatically. For example, if a shiny new app-xyz was recently added, you can pull it into your local git with:

git submodule init apps/xyz
git submodule update apps/xyz
cd apps/xyz
git checkout master


A diff check for each module can be done with:

git submodule foreach git diff



For the day-to-day bug fixes and minor feature enhancements, feel free to use the master branch directly. For major changes or long term projects, use a branch.

Commits to the Super-Project

When you have committed changes to apps, the pointers inside the super-project will be out of date.

cd ~/clearos # or wherever your top-level checkout lives
git status

# On branch master
# Changed but not updated:
#   (use "git add ..." to update what will be committed)
#   (use "git checkout -- ..." to discard changes in working directory)
#	modified:   apps/base (new commits)
#	modified:   apps/marketplace (new commits)

Please do not commit these changes! From time to time, we will update the super-project, but it is not a requirement for our current workflow.

content/en_us/dev_framework_tutorials_comprehensive_development_environment_and_source.txt · Last modified: 2015/03/02 16:02 by dloper