diff options
| -rw-r--r-- | .github/workflows/build.yml | 8 | ||||
| -rw-r--r-- | INSTALL.md | 242 | ||||
| -rw-r--r-- | Makefile | 48 | ||||
| -rw-r--r-- | README.md | 228 | ||||
| -rw-r--r-- | release/tarball-README | 46 |
5 files changed, 357 insertions, 215 deletions
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index bf6ae250..145637d9 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -57,14 +57,14 @@ jobs: run: | ccache --zero-stats --max-size 250M export PATH=/usr/lib/ccache:$PATH - make -j3 GHCJOBS=2 GHCRTSFLAGS='+RTS -M5G -A128m -RTS' + make -j3 GHCJOBS=2 GHCRTSFLAGS='+RTS -M5G -A128m -RTS' install-src tar czf inst.tar.gz inst - name: CCache stats env: CCACHE_DIR: ${{ GITHUB.WORKSPACE }}/ccache run: ccache --show-stats - name: Smoketest - run: "make check" + run: "make check-smoke" # Check that .ghci has all the right flags to load the source. # This is important for text editor integration & tools like ghcid # NB stp, yices and htcl must be built first, so do this after Build. @@ -133,14 +133,14 @@ jobs: # binary. rm -f /usr/local/include/tcl.h - make -j3 GHCJOBS=2 GHCRTSFLAGS='+RTS -M4500M -A128m -RTS' MACOSX_DEPLOYMENT_TARGET=10.13 + make -j3 GHCJOBS=2 GHCRTSFLAGS='+RTS -M4500M -A128m -RTS' MACOSX_DEPLOYMENT_TARGET=10.13 install-src tar czf inst.tar.gz inst - name: CCache stats env: CCACHE_DIR: ${{ GITHUB.WORKSPACE }}/ccache run: ccache --show-stats - name: Smoketest - run: "make check" + run: "make check-smoke" # Check that .ghci has all the right flags to load the source. # This is important for text editor integration & tools like ghcid # NB stp, yices and htcl must be built first, so do this after Build. diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..b6956ed7 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,242 @@ +# Compiling BSC from source + +Source code for the Bluespec toolchain can currently be built on Linux +and MacOS. It may compile for other flavors of Unix, but likely will need +additional if/else blocks in source code or Makefiles. + +The core of BSC is written in Haskell, with some libraries in C/C++. + +--- + +## Overview + +The following sections describe the requirements and commands for building +BSC. Running the build commands will result in the creation of a directory +(named 'inst' by default) that contains an _installation_ of BSC. This +directory can be moved to anywhere on your system, but it is best for the +files to remain in their relative positions within the directory. + +We recommend renaming the `inst` directory to `bsc-<VERSION>` and placing +it in a subdirectory of `/opt/`, `${HOME}/`, `/usr/share/`, or similar +location. For example: + + $ mkdir -p /opt/tools/bsc + $ mv inst /opt/tools/bsc/bsc-4.0.0 + $ cd /opt/tools/bsc + $ ln -s bsc-4.0.0 latest + +The 'inst' directory has a 'bin' subdirectory, where the executables +for the tools are found. To use the tools, just add that directory to +your `PATH`: + + $ export PATH=/opt/tools/bsc/latest/bin:$PATH + +These executables will make use of other files found within the `inst` +directory, locating them relatively from the `bin` directory. That is +why the directory must be kept together. + +If you are packaging BSC for an OS (for example, into a `.deb` or `.rpm` +file), your package can't simply move the `bin` files to `/usr/bin/` +and the `lib` files to `/usr/lib/` and so on. We recommend placing the +`inst` directory at `/usr/share/bsc/bsc-<VERSION>` and then creating +symlinks in `/usr/bin/` that point to the executables in +`/usr/share/bsc/bsc-<VERSION>/bin/`. + +--- + +## Install the Haskell compiler (GHC) + +You will need the standard Haskell compiler `ghc` which is available for Linux, +macOS and Windows, along with some additional Haskell libraries. These are +available as standard packages in most Linux distributions. For example, on +Debian and Ubuntu systems, you can say: + + $ apt-get install ghc + $ apt-get install \ + libghc-regex-compat-dev \ + libghc-syb-dev \ + libghc-old-time-dev \ + libghc-split-dev + +The second command will install the Haskell libraries `regex-compat`, `syb`, +`old-time`, and `split`, as well as some libraries that they depend on. + +If you wish to do profiling builds of the compiler itself, you will also need +to install versions of the Haskell libraries built using the profiling flags. +On Debian and Ubuntu, this can be done with: + + $ apt-get install \ + ghc-prof \ + libghc-regex-compat-prof \ + libghc-syb-prof \ + libghc-old-time-prof \ + libghc-split-prof + +You can do the analogous package-install on other Linux distributions using +their native package mechanisms, and on macOS using Homebrew or Macports. Full details +can be found at <https://www.haskell.org/>, and in particular `ghcup` is a popular +installer for recent Haskell releases <https://www.haskell.org/ghcup/>. + +On some systems, you may need to use the `cabal` command to install Haskell +libraries. This tool is installed by `ghcup` but is also available as a package +for many distributions. +If you are using cabal 3.0 or later, you will need to use the legacy `v1-` +commands to install Haskell libraries. + +For cabal v2.x: + + $ cabal update + $ cabal install regex-compat syb old-time split + +For cabal v3.x: + + $ cabal update + $ cabal v1-install regex-compat syb old-time split + +Bluespec compiler builds are tested with GHC 7.10.1 and greater, and older +GHC releases are not supported. + +Beyond that, any version up to 8.10.1 (the latest at the time of writing) will +work, since the source code has been written with extensive preprocessor macros +to support every minor release since. + +## Additional requirements + +For building and using the Bluespec Tcl shell (`bluetcl`), +you will need the `tcl` library: + + $ apt-get install tcl-dev + +Building BSC also requires standard Unix shell and Makefile utilities. + +The repository for [the Yices SMT Solver](https://github.com/SRI-CSL/yices2) is +cloned as a submodule of this repository. Building the BSC tools will recurse +into this directory and build the Yices library for linking into BSC and +Bluetcl. Yices currently requires `autoconf` and the `gperf` perfect hashing +library to compile: + + $ apt-get install \ + autoconf \ + gperf + +Building the BSC tools will also recurse into a directory for the STP SMT +solver. This is currently an old snapshot of the STP source code, including the +code for various libraries that it uses. In the future, this may be replaced +with a submodule instantiation of the repository for [the STP SMT +solver](https://github.com/stp/stp). When that happens, additional requirements +from that repository will be added. The current snapshot requires Perl, to +generate two source files. It also needs flex and bison: + + $ apt-get install flex bison + +The `check` target runs a test using an external Verilog simulator, which is +[Icarus Verilog] by default. You can install Icarus on Debian/Ubuntu with: + + $ apt-get install iverilog + +[Icarus Verilog]: http://iverilog.icarus.com + +The `install-doc` target builds PDF documentation from LaTeX source files +that rely on a few standard style files. The following Debian/Unbuntu +packages install sufficient tools to build the documentation: + + $ apt-get install \ + texlive-latex-base \ + texlive-latex-recommended \ + texlive-latex-extra \ + texlive-font-utils \ + texlive-fonts-extra + +## Clone the repository + +Clone this repository by running: + + $ git clone --recursive https://github.com/B-Lang-org/bsc + +That will clone this repository and all of the submodules that it depends on. +If you have cloned the repository without the `--recursive` flag, you can setup +the submodules later with a separate command: + + $ git clone https://github.com/B-Lang-org/bsc + $ git submodule update --init --recursive + +## Build and test the toolchain + +At the root of the repository: + + $ make install + $ make check + +This will create a directory called `inst` containing an installation of the +compiler toolchain. It will then run a smoke test to ensure the compiler and +simulator work properly. This `inst` directory can later be moved to another +location; the tools do not hard-code the install location. + +If you wish, you can install into another location by assigning the variable +`PREFIX` in the environment: + + $ make PREFIX=/opt/tools/bsc/bsc-<VERSION> + +However, note that the `clean` target will delete the `PREFIX` directory! + +An unoptimized, debug, or profiling build can be done using one of: + + $ make BSC_BUILD=NOOPT + $ make BSC_BUILD=DEBUG + $ make BSC_BUILD=PROF + +For more extensive testing, see the [testsuite README](testsuite/README.md) +in the `testsuite` subdirectory. + +### Choosing a Verilog simulator + +The Makefile in `examples/smoke_test` shows how you can point the default +`check` target at other Verilog simulators such as VCS and VCSI (Synopys), +NC-Verilog & NCsim (Cadence), ModelSim (Mentor), and CVC. + +Many people also use [Verilator][] to compile and simulate `bsc`-generated +Verilog -- but you must write your own C++ harness for your design in order to +use it. + +[Verilator]: https://www.veripool.org/wiki/verilator + +## Build documentation + +To build and install the PDF documentation, you can add the following: + + $ make install-doc + +This will install into the same `inst` or `PREFIX` directory. +The installed documents include the BSC User Guide and the BSC Libraries +Reference Guide. + +--- + +## Using the Bluespec compiler + +The installation contains a `bin` directory. To run the BSC tools, you only +need to add the `bin` directory to your path (or provide that path on the +command line). The executables in that directory will expect to find other +files in sibling directories within that same parent installation directory. If +you just built the compiler, you can quickly test it like so: + + $ export PATH=$(pwd)/inst/bin:$PATH + +> **NOTE**: Earlier versions of BSC required that the environment variable +> `BLUESPECDIR` be set to point into the installation directory; this is no +> longer necessary, as the executables will figure out their location and +> determine the installation location on their own. + +Run the following to see command-line options on the executable: + + $ bsc -help + +Additional flags of use to developers can be displayed with the +following command: + + $ bsc -help-hidden + +More details on using BSC, Bluesim, and Bluetcl can be found in the User Guide +(built in this repository). +Language documentation, training, and tutorials can be found in the +[BSVlang repository](https://github.com/BSVLang/Main). @@ -4,8 +4,25 @@ TOP := $(PWD) PREFIX ?= $(TOP)/inst BUILDDIR ?= $(TOP)/build -.PHONY: all -all: install +.PHONY: help +help: + @echo 'This Makefile will create an installation of the Bluespec Compiler tools,' + @echo 'in a directory named "inst". This directory can be moved anywhere, but' + @echo 'the contents should remain in the same relative locations. Intermediate' + @echo 'files are stored in a directory named "build". The "clean" target will' + @echo 'delete the "build" directory; the "full_clean" target will delete both' + @echo 'the "build" and "inst" directories.' + @echo + @echo ' make release Build a release dir with the tools and docs' + @echo + @echo ' make install-src Build and install just the tools' + @echo ' make install-doc Build and install just the documentation' + @echo + @echo ' make check-smoke Run a quick smoke test' + @echo ' make check-suite Run the test suite (this will take time!)' + @echo + @echo ' make clean Remove intermediate build-files unnecessary for execution' + @echo ' make full_clean Restore to pristine state (pre-building anything)' # ------------------------- @@ -19,27 +36,38 @@ rem_build: # ------------------------- -.PHONY: install -install: +.PHONY: install-src +install-src: $(MAKE) -C src PREFIX=$(PREFIX) install .PHONY: install-doc install-doc: $(MAKE) -C doc PREFIX=$(PREFIX) install -# In the future, this will be much more expansive, and run the actual test -# suite once it's open sourced. -# +.PHONY: install-README + cp release/tarball-README $(PREFIX)/README + +# ------------------------- + +.PHONY: release +release: install-src install-doc install-README + +# ------------------------- + # NOTE: We have to do things in a subshell and set PATH there, because the # generated bluesim .exe is a shell script that expects 'bluetcl' to be located # in $PATH. it's not enough to just set bsc... -.PHONY: check -check: +.PHONY: check-smoke +check-smoke: @(export PATH=$(PREFIX)/bin:$(PATH); $(MAKE) -C examples/smoke_test smoke_test) +.PHONY: check-suite +check-suite: + $(MAKE) -C testsuite + # ------------------------- -clean: rem_inst rem_build +clean: rem_build -$(MAKE) -C src clean -$(MAKE) -C doc clean @@ -2,20 +2,19 @@ # Bluespec Compiler -![Version] [![Build Status]](https://github.com/b-lang-org/bsc/actions?query=workflow%3ACI+event%3Apush) +![Version] [![License]](./COPYING) [![Build Status]](https://github.com/b-lang-org/bsc/actions?query=workflow%3ACI+event%3Apush) -[![Documentation]][Doc page] -[![License]](./COPYING) - -[Doc page]: https://github.com/B-Lang-org/bsc -[Documentation]: https://img.shields.io/badge/docs-Manual-orange.svg?logo=markdown [License]: https://img.shields.io/badge/license-BSD%203-blueviolet.svg [Version]: https://img.shields.io/badge/release-2020.02,%20"Open%20Source%20Release"-red.svg?logo=v [Build Status]: https://github.com/b-lang-org/bsc/workflows/CI/badge.svg?branch=main&event=push -<strong> - <a href="https://github.com/B-Lang-org/bsc">Homepage</a> • <a href="https://github.com/B-Lang-org/bsc">Get Started</a> -</strong> +**[Community] • [Download] • [Documentation] • [Build] • [Test]** + +[Community]: #community +[Download]: #download +[Documentation]: #documentation +[Build]: ./INSTALL.md +[TEST]: ./testsuite/README.md --- @@ -87,209 +86,36 @@ Feel free to give it a try and see if it can be useful to our community. --- -## Compiling BSC from source - -Binaries for the Bluespec toolchain are currently unavailable, so you must -build them from source code. The source code can currently be built on Linux -and MacOS. It may compile for other flavors of Unix, but likely will need -additional if/else blocks in source code or Makefiles. - -The core of BSC is written in Haskell, with some libraries in C/C++. - -### Install the Haskell compiler (GHC) - -You will need the standard Haskell compiler `ghc` which is available for Linux, -macOS and Windows, along with some additional Haskell libraries. These are -available as standard packages in most Linux distributions. For example, on -Debian and Ubuntu systems, you can say: - - $ apt-get install ghc - $ apt-get install \ - libghc-regex-compat-dev \ - libghc-syb-dev \ - libghc-old-time-dev \ - libghc-split-dev - -The second command will install the Haskell libraries `regex-compat`, `syb`, -`old-time`, and `split`, as well as some libraries that they depend on. - -If you wish to do profiling builds of the compiler itself, you will also need -to install versions of the Haskell libraries built using the profiling flags. -On Debian and Ubuntu, this can be done with: - - $ apt-get install \ - ghc-prof \ - libghc-regex-compat-prof \ - libghc-syb-prof \ - libghc-old-time-prof \ - libghc-split-prof - -You can do the analogous package-install on other Linux distributions using -their native package mechanisms, and on macOS using Homebrew or Macports. Full details -can be found at <https://www.haskell.org/>, and in particular `ghcup` is a popular -installer for recent Haskell releases <https://www.haskell.org/ghcup/>. - -On some systems, you may need to use the `cabal` command to install Haskell -libraries. This tool is installed by `ghcup` but is also available as a package -for many distributions. -If you are using cabal 3.0 or later, you will need to use the legacy `v1-` -commands to install Haskell libraries. - -For cabal v2.x: - - $ cabal update - $ cabal install regex-compat syb old-time split - -For cabal v3.x: - - $ cabal update - $ cabal v1-install regex-compat syb old-time split - - -Bluespec compiler builds are tested with GHC 7.10.1 and greater, and older -GHC releases are not supported. - -Beyond that, any version up to 8.10.1 (the latest at the time of writing) will -work, since the source code has been written with extensive preprocessor macros -to support every minor release since. - -### Additional requirements - -For building and using the Bluespec Tcl shell (`bluetcl`), -you will need the `tcl` library: - - $ apt-get install tcl-dev - -Building BSC also requires standard Unix shell and Makefile utilities. - -The repository for [the Yices SMT Solver](https://github.com/SRI-CSL/yices2) is -cloned as a submodule of this repository. Building the BSC tools will recurse -into this directory and build the Yices library for linking into BSC and -Bluetcl. Yices currently requires `autoconf` and the `gperf` perfect hashing -library to compile: - - $ apt-get install \ - autoconf \ - gperf - -Building the BSC tools will also recurse into a directory for the STP SMT -solver. This is currently an old snapshot of the STP source code, including the -code for various libraries that it uses. In the future, this may be replaced -with a submodule instantiation of the repository for [the STP SMT -solver](https://github.com/stp/stp). When that happens, additional requirements -from that repository will be added. The current snapshot requires Perl, to -generate two source files. It also needs flex and bison: - - $ apt-get install flex bison +## Download -The `check` target runs a test using an external Verilog simulator, which is -[Icarus Verilog] by default. You can install Icarus on Debian/Ubuntu with: +For the following systems, the Bluespec toolchain is available +as a package that can be installed with the standard package manager: - $ apt-get install iverilog +* Nix/NixOS: [`bluespec`](https://search.nixos.org/packages?channel=20.09&from=0&size=50&sort=relevance&query=bluespec) -[Icarus Verilog]: http://iverilog.icarus.com +If a package exists for your system, we recommend installing that. +Otherwise, a tar-archive may be available for download from our +[Releases](https://github.com/B-Lang-org/bsc/releases) page. +Install instructions can be found inside the tar-file. -The `install-doc` target builds PDF documentation from LaTeX source files -that rely on a few standard style files. The following Debian/Unbuntu -packages install sufficient tools to build the documentation: - - $ apt-get install \ - texlive-latex-base \ - texlive-latex-recommended \ - texlive-latex-extra \ - texlive-font-utils \ - texlive-fonts-extra - -### Clone the repository - -Clone this repository by running: - - $ git clone --recursive https://github.com/B-Lang-org/bsc - -That will clone this repository and all of the submodules that it depends on. -If you have cloned the repository without the `--recursive` flag, you can setup -the submodules later with a separate command: - - $ git clone https://github.com/B-Lang-org/bsc - $ git submodule update --init --recursive - -### Build and test the toolchain - -At the root of the repository: - - $ make install - $ make check - -This will create a directory called `inst` containing an installation of the -compiler toolchain. It will then run a smoke test to ensure the compiler and -simulator work properly. This `inst` directory can later be moved to another -location; the tools do not hard-code the install location. - -If you wish, you can install into another location by assigning the variable -`PREFIX` in the environment: - - $ make PREFIX=/tools/bluespec - -An unoptimized, debug, or profiling build can be done using one of: - - $ make BSC_BUILD=NOOPT - $ make BSC_BUILD=DEBUG - $ make BSC_BUILD=PROF - -For more extensive testing, see the [testsuite README](testsuite/README.md) -in the `testsuite` subdirectory. - -#### Choosing a Verilog simulator - -The Makefile in `examples/smoke_test` shows how you can point the default -`check` target at other Verilog simulators such as VCS and VCSI (Synopys), -NC-Verilog & NCsim (Cadence), ModelSim (Mentor), and CVC. - -Many people also use [Verilator][] to compile and simulate `bsc`-generated -Verilog -- but you must write your own C++ harness for your design in order to -use it. - -[Verilator]: https://www.veripool.org/wiki/verilator - -### Build documentation - -To build and install the PDF documentation, you can add the following: - - $ make install-doc - -This will install into the same `inst` or `PREFIX` directory. -The installed documents include the BSC User Guide and the BSC Libraries -Reference Guide. +If a pre-built tar-file does not exist for your system, +you will need to [compile BSC from source](INSTALL.md). --- -## Using the Bluespec compiler - -The installation contains a `bin` directory. To run the BSC tools, you only -need to add the `bin` directory to your path (or provide that path on the -command line). The executables in that directory will expect to find other -files in sibling directories within that same parent installation directory. If -you just built the compiler, you can quickly test it like so: - - $ export PATH=$(pwd)/inst/bin:$PATH - -> **NOTE**: Earlier versions of BSC required that the environment variable -> `BLUESPECDIR` be set to point into the installation directory; this is no -> longer necessary, as the executables will figure out their location and -> determine the installation location on their own. - -Run the following to see command-line options on the executable: +## Documentation - $ bsc -help +More details on using BSC, Bluesim, and Bluetcl can be found in the +_BSC User Guide_. -Additional flags of use to developers can be displayed with the -following command: +The standard libraries that come with BSC are documented in the +_BSC Libraries Reference Guide_. - $ bsc -help-hidden +The sources for both of these documents are found in the `doc` +directory of this repo. Pre-built PDF files can be downloaded from +the [Releases](https://github.com/B-Lang-org/bsc/releases) page. -More details on using BSC, Bluesim, and Bluetcl can be found in the User Guide -(built in this repository). -Training and tutorials can be found in the +Language documentation, training, and tutorials can be found in the [BSVlang repository](https://github.com/BSVLang/Main). --- diff --git a/release/tarball-README b/release/tarball-README new file mode 100644 index 00000000..e3a184f1 --- /dev/null +++ b/release/tarball-README @@ -0,0 +1,46 @@ +This directory contains an installation of the Bluespec Compiler tools. + +For more information, visit https://github.com/B-Lang-org/bsc + +------------------------- + +This directory can be moved to anywhere on your system, but it is best +for the files to remain in their relative positions within the +directory. + +We recommend placing this directory under `/opt`, `${HOME}/`, +`/usr/share/`, or similar location. For example: + + $ mkdir -p /opt/tools/bsc + $ mv bsc-<VERSION> /opt/tools/bsc/bsc-<VERSION> + $ cd /opt/tools/bsc + $ ln -s bsc-<VERSION> latest + +This directory has a 'bin' subdirectory, where the executables for the +tools are found. To use the tools, just add that directory to your +`PATH`: + + $ export PATH=/opt/tools/bsc/latest/bin:$PATH + +These executables will make use of other files found within this +directory, locating them relatively from the `bin` directory. That is +why the directory must be kept together. + +------------------------- + +Run the following to see command-line options on the executable: + + $ bsc -help + +Additional flags of use to developers can be displayed with the +following command: + + $ bsc -help-hidden + +More details on using BSC, Bluesim, and Bluetcl can be found in the +BSC User Guide, in the `doc` subdirectory. + +Links to more documentation can be found on the BSC website: +https://github.com/B-Lang-org/bsc + +------------------------- |