Difference between revisions of "Building the Code"

From UntangleWiki
Jump to: navigation, search
(Getting the code)
Line 103: Line 103:
See [[Application Developers Guide]]
See [[Application Developers Guide]]
== Getting help ==
You can ask for help on [[IRC]].

Latest revision as of 16:42, 30 March 2018

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. Note that the build dependencies are only guaranteed to be satisfied for the current stable branch (for instance, release-13.1 is the current official release is 13.1). Trying to build master can occasionally require additional dependencies.

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.
  • debian/: the debian packaging information
  • i18n-tools/: the i18n/translation tools
  • <component-name>: directory for each app, library, or component. (uvm, libnetcap, firewall, etc)

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