Skip to content

Latest commit

 

History

History
240 lines (171 loc) · 8.72 KB

How_to_Contribute.adoc

File metadata and controls

240 lines (171 loc) · 8.72 KB
Raw

How to Contribute to bsc-contrib

Let’s assume you want to contribute a new library MyContrib. All your B-Lang (BSV/BH) sources and documentation should be placed in a new sub-directory:

bsc-contrib/Libraries/MyContrib/

If your BSV/BH code imports any Verilog, it should be placed in:

bsc-contrib/Verilog/

If you also have unit tests, they should be in a new sub-directory:

bsc-contrib/testing/bsc.contrib/Unit_Test_MyContrib
Note
 In future we may require unit tests also to be in bsc-contrib/Libraries/MyContrib/`

This document should help you prepare your contribution, within your own fork of the bsc-contrib repository, before issuing a Pull Request (PR).

1. Logistics

We suggest the following "flow":

  • On GitHub, create a FORK of the original bsc-contrib repository, under your own account.

  • Clone your FORK to your work area (laptop, desktop, …​).

  • Create a new BRANCH in your clone of your FORK.

  • In this new BRANCH (in your clone of your FORK), prepare your contribution, including formatting, copyrights, licenses, build-and-install Makefiles and optional unit tests. See the sections below for details.

  • Commit your BRANCH.

  • Please "squash" any "uninteresting" older commits so that the PR contains only useful commits (that a future maintainer may find useful). In most cases, one can squash everything into a single, final commit on top of the most recent bsc-contrib commit.

  • Push the commit from your clone up to your FORK.

  • From your FORK, create a PR for the original bsc-contrib repository.

2. Source text formatting

Source text formatting is checked automatically during CI (continuous integration).

At the moment the only check is to disallow trailing blanks, particularly in source files.

Note
 We may add more detailed format-checkers in future.

3. Copyright and License text

Make sure all files (code files, Makefiles, READMEs, …​) have your desired Copyright and License text. Example:

// Copyright (c) 2020 Bluespec, Inc. All rights reserved.
//
// SPDX-License-Identifier: BSD-3-Clause

You are responsible for specifying your preferred copyright and license text (but please remember that this is a public repository; everything here is expected to be free and open-source; anything here should be freely usable in commercial products).

You can insert full license text or, if it is a standard well-known license, just provide its SPDX identifier as in the example above. If you’re undecided, we recommend BSD-3-Clause.

4. README

It is normally good to have a README file in your contribution:

Libraries/MyContrib/README{,.txt,.md,.adoc}

Plain-text (no extension or .txt extension), Markdown (.md) or AsciiDoctor (.adoc) are automatically rendered by GitHub.

5. Makefiles for building and installing

make all at the top level descends recursively into all sub-directories of Libraries and Verilog. In a leaf-level library directory the Makefile contains a build target to compile source file(s) that are in that directory. The corresponding object files get copied into the installation directory (default bsc-contrib/inst). You can also specify other files to be copied (include files, config files, …​).

If you added any files to the Verilog/ directory, add those filenames to the VERI_FILES list in the Verilog/Makefile.

The top-level make all is performed for installation, but is also repeated automatically during CI (continuous integration) to check that it succeeds.

Note
 In the Library sub-directories, this just compiles sources, it does not build executables. See separate "Unit Tests" section for building unit test executables and running them. Those are also performed by CI.

5.1. Setting up Makefiles for build-and-install of MyContrib

In the existing

Libraries/Makefile

add MyContrib to the BUILD_ORDER list in order to include your contribution into the recursive descent.

If Libraries/MyContrib/ has sub-directories, repeat the recursive pattern of Libraries/Makefile to enable recursive descent into each sub-directory, as needed. Example:

Libraries/AMBA_TLM2/Makefile

Finally, at leaf level, have a Makefile that does the actual work. Example:

Libraries/AMBA_TLM2/AHB/Makefile

  • Make sure it defines TOP and LIBNAME

  • It should compile each of the source files in MyLibrary (either directly, or via import into another source file). The corresponding object files are placed in the "install" area by the make invocation.

Note
 Many of these Makefiles include Libaries/common.mk for defaults and then selectively override defaults. It expects Makefile variables TOP and LIBNAME to be set.

5.2. Running build-and-install

Please run this before submitting a PR to ensure it all works. In your copy (clone of fork) of bsc-contrib:

$ cd bsc-contrib    // my clone of my fork
$ make all

This should run the make install action on the whole repository, including compiling your sources in your newly added MyContrib, and installing the corresponding object files in:

bsc-contrib/inst/lib/Libraries/MyContrib/

6. Optional Unit Tests

You can optionally add unit tests for your library source files; these unit tests are run automatically and repeatedly as part of CI (Continuous Integration).

Note
 bsc-contrib 's unit testing is performed as part of the main bsc compiler’s testing of standard libraries, using the same infrastructure. The infrastructure has many more ways to configure testing than the brief description here; please see testsuite/README.md in the bsc repository for more details (https://github.com/B-Lang-org/bsc).

Add your unit tests to bsc-contrib/testing/bsc.contrib/. For guidance, you can study any of the existing unit tests in that directory or in testsuite/ in the bsc compiler repository. Briefly:

  • Add a sub-directory for a new set of unit tests for the new library (it can have sub-directories for more detailed structure):

    bsc-contrib/testing/bsc.contrib/MyContrib/

  • In this directory:

    • There should be a Makefile that is just boilerplate; see any of the other unit test directories for examples.

    • You can have multiple test programs. Each such top-level Foo.bsv (or Foo.bs) should contain a top-level module sysFoo with an Empty interface.

    • If the top-level file imports other support source files (just for this test, not library files), they can be placed here, too.

    • Create a file sysFoo.out.expected containing output expected when it is run.

      If different output is expected from Bluesim vs. Verilog sim (e.g., $time can be slightly different), you can instead have separate files for each:

      • for Bluesim: sysFoo.c.out.expected

      • for Verilog: sysFoo.v.out.expected

    • Finally, a file foo.exp contains a fragment of a "script" to be run in this directory. It can invoke multiple tests in this directory. Each test can be run in Bluesim or Verilog sim or both. Again, see other existing unit tests for examples.

      For unit tests included in the .exp file, try to keep the run-time short (no more than about a minute) when run in iverilog, to limit the overall run-time of CI (Continuous Integration).

6.1. Running unit tests

Please run your tests before submitting a PR.

See the "Testing" section of the README in bsc-contrib for information on how to run them (you have to copy testing/bsc.contrib from here into the bsc repository’s testsuite directory and run it there).

Note
 (Future restructuring plans)
We would like unit tests for library MyContrib to be located along with its sources, i.e., under Libraries/MyContrib, instead of separately in testing/bsc.contrib/MyContrib. The current structure exists because it is derived from historical roots where bsc-contrib 's testing was done along with bsc 's testing using shared infrastructure in the bsc repository.