Building the Code

From UntangleWiki
Revision as of 17:01, 17 January 2016 by Dmorris (talk | contribs) (The Developer Build)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Build Requirements

For a development build, we recommend starting from an Untangle ISO install and converting it into a developer box.

  • insert the CD and reboot to install Untangle; this will wipe out any operating system previously installed.
  • when the system reboots, use the setup wizard to configure the box for your network.
  • click on the 'terminal' button to get access to a shell: you will be asked for a new root password the first time you access the shell.
  • Disable the production untangle-vm:
$ /etc/init.d./untangle-vm stop
$ rm -f /etc/init.d/untangle-vm
  • reconfigure debconf, and select 'Dialog' as the interface and keep other settings as the default:
$ dpkg-reconfigure debconf
  • install the 'untangle-development' package:
$ apt-get update
$ apt-get --yes install untangle-development-build

Getting the Source

The source is hosted on GitLab.

Planning on contributing

If you plan on submitting merge requests to us, it's recommended you open a GitLab account, clone our main repository, and check that out using git.

Getting the code

For instance if you named your clone "src-yours", you would use the following command (after having uploaded a valid public SSH key to GitLab):

$ git clone<your-gitorious-user>/

Sending us your changes

First, push your changes back to GitLab; roughly, it should go something like (from your working directory):

 git commit -a                                                 (1)
 git pull --rebase git:// master (2)
 git push                                                      (3)
(1) is to commit locally, no svn equivalent
(2) is to get your copy up-to-date (think "svn up")
(3) is to push to GitLab (think "svn commit")

Then, create a merge request using the GitLab interface: click on "merge", and follow the assistant (make sure you ask for a merge to our main untangle:src repository, in the master branch); we'll get your request automatically.

Anonymous cloning

You can also anonymously clone our main repository, using the following command:

$ git clone git://

Building Core

The Untangle build system works in two modes:

  • Developer Build: installs the product locally (in the 'dist/' directory) so that it can be run directly from the development environment.
  • Package Build: creates a set of Debian packages that can be installed using apt-get/dpkg.

The Developer Build

We recommend the Developer Build for those wishing to write Nodes and extend the system, since it allows for a shorter develop->build->test cycle time.

In this mode, the core of the system is functional, but some integration and peripheral functionality may be disabled or non-functional.

Actual building is simple: change to the directory you cloned using git, and run:

$ rake

Upon successful build (this may take a while), the system should be fully built and installed in the 'dist/' directory.

You can then start the untangle-vm by running:

$ sudo ./dist/etc/init.d/untangle-vm start

You should be able to access the administrative gui at http://localhost/webui. The default login is "admin" with the password of "passwd"

The "dist/" directory has all the files in the same hierarchy as they would normally be found on your filesystem after a normal installation. To troubleshoot any potential issues, you can look at log files in 'dist/var/log/uvm', with 'uvm.log' usually being the most interesting.

The Package Build

The Package Build allows fuller integration and enables all features of the product. Some functionality may be disabled or non-functional.

Change to the directory you cloned using git, and then issue:

$ perl -pe 's/^deb/deb-src/' /etc/apt/sources.list.d/untangle.list > /etc/apt/sources.list.d/untangle-sources.list
$ apt-get update
$ apt-get build-dep untangle-vm
$ debuild -us -uc

The resulting Debian packages will be built one level up ('..'):

$ dpkg -i ../untangle-*deb

Filesystem Hierarchy

Source Hierarchy

The src/ hierarchy contains:

  • buildtools/: scripts and libraries used by the build system.
  • rakefile: main rakefile.
  • <component>-name: directory for each Node, Casing, and Component.
  • prj.el: Emacs JDEE Project file.
  • G*: GNU Global tag files

A build results in the following artifacts:

  • dist/: result of a developer build, mirrors the directory structure of an installed system.
  • staging/: compiled classes and other pre-install artifacts.
  • taskstamps.txt: stamp file for build targets.

Component Hierarchy

See Application Developers Guide

Getting help

You can ask for help on IRC.