Building the Code

From UntangleWiki
Revision as of 17:03, 18 September 2016 by Dmorris (talk | contribs)

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-build' package:
$ apt-get update
$ apt-get --yes install untangle-development-build

Getting the Source

The source is hosted on GitHub.

Getting the code

Fork both our main repositories (src and pkgs), and clone them using git.

Sending us your changes

Create pull requests targetting the master branch.

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 apps 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.

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.