Difference between revisions of "Source code"

From VyOS Wiki
Jump to: navigation, search
m (typo)
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
{{Migrated | url = https://vyos.readthedocs.io/en/latest/contributing/development.html}}
 
The '''source code''' is hosted on github under VyOS organization: [https://github.com/vyos github.com/vyos].
 
The '''source code''' is hosted on github under VyOS organization: [https://github.com/vyos github.com/vyos].
  
Line 6: Line 7:
  
 
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.
 
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 [https://github.com/vyos/vyos-build vyos-build].
  
 
Technically it looks like this:
 
Technically it looks like this:
Line 11: Line 15:
 
build-iso/
 
build-iso/
 
     .git/
 
     .git/
 +
      modules/
 +
        packages/
 +
          pkg-foo/
 +
          pkg-bar/
 
     .gitmodules
 
     .gitmodules
     pkgs/
+
     packages/
 
         pkg-foo/
 
         pkg-foo/
            .git/
 
 
         pkg-bar/
 
         pkg-bar/
            .git/
 
 
</pre>
 
</pre>
  
 
.gitmodules it the file that hold the submodule list. Normally you don't need to edit it manually.
 
.gitmodules it the file that hold the submodule list. Normally you don't need to edit it manually.
  
When you clone the build-iso.git, pkgs/ subdirectories are empty. Their contents are stored in separate remote repositories.
+
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 [http://git-scm.com/book/en/Git-Tools-Submodules git book] or "man git-submodule".
 
You can read mode about submodules in the [http://git-scm.com/book/en/Git-Tools-Submodules git book] or "man git-submodule".
Line 32: Line 38:
  
 
<pre>
 
<pre>
git clone https://github.com/vyos/build-iso.git
+
git clone https://github.com/vyos/vyos-build.git
 
</pre>
 
</pre>
  
 
If you want to modify a package, you need to init and update its submodule. Say you want to modify vyatta-cfg-system.
 
If you want to modify a package, you need to init and update its submodule. Say you want to modify vyatta-cfg-system.
 
<pre>
 
<pre>
git submodule update --init pkgs/vyatta-cfg-system
+
git submodule update --init packages/vyos-1x
 
</pre>
 
</pre>
  
After that you will have vyatta-cfg-system source code under pkgs/vyatta-cfg-system directory.
+
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 ==
 
== 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.
 
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 "hydrogen" branch):
+
You can then add the branch to your local copy (e.g. for "lithium" branch):
 
<pre>
 
<pre>
git branch hydrogen --track origin/hydrogen
+
git branch lithium --track origin/lithium
git checkout hydrogen
+
git checkout lithium
 
</pre>
 
</pre>
  
You need to do it in both build-iso repository and submodules you are going to modify.
+
You need to do it in both vyos-build repository and submodules you are going to modify.
  
 
== Building a submodule ==
 
== Building a submodule ==
Line 61: Line 75:
 
</pre>
 
</pre>
  
Once you are ready to test the modifications you made to the package, you can build it from the top level directory as easy as:
+
Once you are ready to test the modifications you made to the package, run "debuild -us -uc" inside it:
 
<pre>
 
<pre>
jrhacker@dev-machine: ~/build-iso$ make vyatta-cfg-system
+
jrhacker@dev-machine: ~/vyos-build$ cd packages/vyos-1x
 +
jrhacker@dev-machine: ~/vyos-1x$ debuild -us -uc
 
</pre>
 
</pre>
  
If the build completes successfully, the .deb will appear under pkgs/
+
If the build completes successfully, the .deb will appear under packages/
  
 
== Pushing the changes to remote ==
 
== 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:
 
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:
* Clone the build-iso.git from the upstream.
+
* Create a task in [https://phabricator.vyos.net phabricator.vyos.net]
 +
* Clone the vyos-build.git from the upstream.
 
* Init the submodule.
 
* 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.
 
* Fork the package you are going to modify to your github account.
* Replace the path to remote in submodule .git/config
+
* 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
  
  
 
[[Category: Development]]
 
[[Category: Development]]

Latest revision as of 21:13, 2 July 2019

Warning sign.png This page is migrated to Readthedocs .
Information found on this page is migrated to readthedocs and information found here could be outdated or misleading. https://vyos.readthedocs.io/en/latest/contributing/development.html

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