Source code

The source code is hosted on github under VyOS organization: github.com/vyos.

Source code structure

The source code is split into git submodules. Submodules is a mechanism for keeping subprojects in separate git repos while being able to access them from the main project.

VyOS is composed of multiple individual packages, some of them are periodically synced with upstream, so keeping the whole source under a single repository would be very inconvenient and slow. There is now an ongoing effort to consolidate all VyOS-specific packages into vyos-1x package, but the basic structure is going to stay the same, just with fewer submodules.

The repository that contains the ISO build scripts and links to all submodules is vyos-build.

Technically it looks like this:

build-iso/
    .git/
      modules/
        packages/
          pkg-foo/
          pkg-bar/
    .gitmodules
    packages/
        pkg-foo/
        pkg-bar/

.gitmodules it the file that hold the submodule list. Normally you don't need to edit it manually.

When you clone the vyos-build.git, packages/* subdirectories are empty. Their contents are stored in separate remote repositories.

You can read mode about submodules in the git book or "man git-submodule".

As every submodule represents a debian package,the terms "submodule" and "package" are used here interchangeably.

Cloning the source code

According to the above, you should clone the main repo (build-iso.git) first. It contains the ISO build scripts and serves as a container for submodules.

git clone https://github.com/vyos/vyos-build.git

If you want to modify a package, you need to init and update its submodule. Say you want to modify vyatta-cfg-system.

git submodule update --init packages/vyos-1x

After that you will have vyos-1x source code under packages/vyos-1x directory.

Note

Change directory to the vyos-build directory to run the git submodule update command.

Branches

The work on the rolling release is done in the current branch. For historical reasons (master branch messed up by development before the fork from Vyatta) we could not use master, so we called it current. In post-fork repositories such as vyos-build and vyos-1x it is kept in sync with master and when all packages are rewritten and consolidated into vyos-1x, we will switch to using master. Right now all pull requests in all submodules have to go to current.

Each new VyOS release gets its own branch. Consult the version history to find out which one is the current.

You can then add the branch to your local copy (e.g. for "lithium" branch):

git branch lithium --track origin/lithium
git checkout lithium

You need to do it in both vyos-build repository and submodules you are going to modify.

Building a submodule

Before you start building submodules, install the following packages:

apt-get install devscripts # Provides debuild

Once you are ready to test the modifications you made to the package, run "debuild -us -uc" inside it:

jrhacker@dev-machine: ~/vyos-build$ cd packages/vyos-1x
jrhacker@dev-machine: ~/vyos-1x$ debuild -us -uc

If the build completes successfully, the .deb will appear under packages/

Pushing the changes to remote

If you do not (yet) have permissions to commit directly to the VyOS upstream, and you are planning to keep your code on github and use pull requests to exchange patches, the best procedure is probably the following:

• Create a task in phabricator.vyos.net
• Clone the vyos-build.git from the upstream.
• Init the submodule.
• Make your modifications and make sure to include the task number in the commit message (e.g. "T42: reduce the complexity of calculating answer to the question of life and universe to O(exp(N))").
• Fork the package you are going to modify to your github account.
• Replace the path to remote in submodule git config (.git/modules/packages/$packageName/config).

Code policy

When modifying the source code, remember these rules of the legacy elimination campaign:

• No new features in Perl
• No old style command definitions
• No code incompatible with Python3