Skip to content

Latest commit

 

History

History
136 lines (101 loc) · 5.29 KB

CONTRIBUTING.md

File metadata and controls

136 lines (101 loc) · 5.29 KB
Raw

Contibuting to webports

The webports project welcomes contributions. The most common forms of contribution are new ports, or updates to existing ports.

Before we can use use your code, you must sign the Google Individual Contributor License Agreement (CLA), which you can do online. The CLA is necessary mainly because you own the copyright to your changes, even after your contribution becomes part of our codebase, so we need your permission to use and distribute your code. We also need to be sure of various other things—for instance that you'll tell us if you know that your code infringes on other people's patents. You don't have to sign the CLA until after you've submitted your code for review and a member has approved it, but you must do it before we can put your code into our codebase. Before you start working on a larger contribution, you should get in touch with us first through the issue tracker with your idea so that we can help out and possibly guide you. Coordinating up front makes it much easier to avoid frustration later on.

Once you have a change that you would like to submit you must upload it for review using:

$ git cl upload

This will upload the change to the code review tool. From there you can send it out for review via the web interface (you can also do this from the command line if you prefer). Once you have an 'lgtm' you can use the commit queue (CQ button in the review tool) to have your change submitted.

Adding a new package

To add a package:

  1. Add a directory to the ports directory using the name your new package. For example: ports/openssl.
  2. Add the build.sh script and pkg_info to that directory.
  3. Optionally include the upstream tarball and add its SHA1 checksum to pkg_info. You can do this using build_tools/sha1sum.py. Redirect the script to append to the pkg_info file. e.g.:
$ sha1sum.py mypkg.tar.gz >> ports/openssl/pkg_info
  1. Optionally include a patch file (nacl.patch). See below for the recommended way to generate this patch.
  2. Make sure your package builds for all architectures:
$ ./make_all.sh <PACKAGE_NAME>

Writing build scripts

Each port has an optional build script: build.sh. Some ports, such as those that are based on autotools+make don't need a build script at all. The build script is run in a bash shell, it can set variables at the global scope that override the default behaviour of various steps in the build process. The most common steps that implement by package-specific scripts are:

  • ConfigureStep()
  • BuildStep()
  • InstallStep()
  • TestStep()

When implementing a given step the default step can be still invoked, e.g. by calling DefaultBuildStep() from within BuildStep().

Each build is is run independently in a subshell, so variables set in one step are not visible in others, and changing the working directory within a step will not effect other steps.

A variety of shared variables and functions are available from with the build scripts. These are defined in build_tools/common.sh.

Modifying package sources / Working with patches

When a package is first built, its source is downloaded and extracted to out/build/<pkg_name>. A new git repository is then created in this folder with the original archive contents on a branch called upstream. The optional nacl.patch file is then applied on the master branch. This means that at any given time you can see the changes from upstream using git diff upstream.

To make changes to a package's patch file the recommended workflow is:

  1. Directly modify the sources in out/build/<pkg_name>.
  2. Build the package and verify the changes.
  3. Use webports updatepatch <pkg_name> to (re)generate the patch file.

Whenever the upstream archive or patch file changes and you try to build the package you will be prompted to remove the existing repository and start a new one. This is to avoid deleting a repository that might contain unsaved changed.

Coding Style

For code that is authored in the webports repository (as opposed to patches) we follow the Chromium style guide: http://www.chromium.org/developers/coding-style.

C/C++ code can be automatically formatted with Chromium's clang-format: https://code.google.com/p/chromium/wiki/ClangFormat. If you have checkout of Chromium you can set CHROMIUM_BUILDTOOLS_PATH=<chromium>/src/buildtools which will enable the clang-format script in depot_tools to find the binary.

Python code can be automatically formatted with the yapf tool which is automatically downloaded during gclient sync. e.g:

$ bin/yapf -i <path/to/my/file.py>

Shell scripts

When modifying any shell scripts in webports it is recommended that you run shellcheck to catch common errors. The recommended command line for this is:

$ shellcheck -e SC2044,SC2129,SC2046,SC2035,SC2034,SC2086,SC2148 \
    `git ls-files "*.sh"`

Commit Messages

Where possible try to follow the generally accepted best practices for git commit messages. That is, a single subject line of 50 characters or less followed by a blank line, followed by a longer description wrapped at 72 characters. For more information of crafted good commit messages see: http://chris.beams.io/posts/git-commit/

Happy porting!