Difference between revisions of "Building the Code"

From UntangleWiki
Jump to: navigation, search
(Getting the Source)
Line 25: Line 25:
 
==Getting the Source==
 
==Getting the Source==
  
The source is hosted on [http://gitlab.com/untangle.com GitLab].
+
The source is hosted on [https://github.com/untangle GitHub].
 
 
=== Planning on contributing ===
 
 
 
If you plan on submitting merge requests to us, it's recommended you open a GitLab account, clone [http://gitlab.com/untangle.com/ngfw_src our main repository], and check that out using git.
 
  
 
==== Getting the code ====
 
==== 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):
+
Fork both our main repositories ([https://github.com/untangle/ngfw_src src] and [https://github.com/untangle/ngfw_pkgs pkgs]), and clone them using git.
 
 
<pre>
 
$ git clone git@gitlab.com:~<your-gitorious-user>/untangle.com/ngfw_src-yours.git
 
</pre>
 
  
 
==== Sending us your changes ====
 
==== Sending us your changes ====
  
First, push your changes back to GitLab; roughly, it should go something like (from your working directory):
+
Create pull requests targetting the master branch.
 
 
  git commit -a                                                (1)
 
  git pull --rebase git://gitlab.com/untangle.com/ngfw_src.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:
 
 
 
<pre>
 
$ git clone git://gitlab.com/untangle.com/ngfw_src.git
 
</pre>
 
  
 
==Building Core==
 
==Building Core==

Revision as of 19:49, 9 August 2016

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