Fix some build issues and update README.

Fixed some bugs in package builder script: * Broken symlink for CDTWasmToolchain.cmake. * Allow package builder script to run with out-of-source builds. Updated description used for generated package. Use leap package for integration tests dependency instead of eosio. Significant changes to README.
2022-08-12 23:03:38 -07:00
parent 07a815e84d
commit 3be7cfec71
5 changed files with 108 additions and 48 deletions
@@ -75,7 +75,7 @@ install(FILES ${CMAKE_BINARY_DIR}/scripts/ricardeos.py DESTINATION ${CDT_INSTALL
 # section for package construction
 set(VENDOR "EOSNetworkFoundation")
 set(PROJECT_NAME "cdt")
-set(DESC "Toolchain and supporting tools for the Leap platform")
+set(DESC "Toolchain and supporting tools to facilitate C/C++ development of contracts for Antelope blockchains")
 set(URL "https://github.com/AntelopeIO/cdt")
 set(EMAIL "bucky.kittinger@eosnetwork.com")
 configure_file(${CMAKE_SOURCE_DIR}/scripts/generate_package.sh.in ${CMAKE_BINARY_DIR}/packages/generate_package.sh @ONLY)
@@ -1,23 +1,39 @@
 # CDT (Contract Development Toolkit)
-## Version : 3.0.0

-CDT is a toolchain for WebAssembly (WASM) and a set of tools to facilitate smart contract development for the Leap platform, a C++ implementation of the Antelope protocol. In addition to being a general purpose WebAssembly toolchain, [Leap](https://github.com/AntelopeIO/leap) specific optimizations are available to support building smart contracts.  This new toolchain is built around [Clang 9](https://github.com/AntelopeIO/cdt-llvm), which means that CDT has the most currently available optimizations and analyses from LLVM, but as the WASM target is still considered experimental, some optimizations are incomplete or not available.
+Contract Development Toolkit (CDT) is a C/C++ toolchain targeting WebAssembly (WASM) and a set of tools to facilitate development of smart contracts written in C/C++ that are meant to be deployed to an [Antelope](https://github.com/AntelopeIO/) blockchain.
+
+In addition to being a general purpose WebAssembly toolchain, specific features and optimizations are available to support building Antelope-based smart contracts. This new toolchain is built around [Clang 9](https://github.com/AntelopeIO/cdt-llvm), which means that CDT inherits the optimizations and analyses from that version of LLVM, but as the WASM target is still considered experimental, some optimizations are incomplete or not available.
+
+## Repo organization
+
+The `main` branch is the development branch: do not use this for production. Refer to the [release page](https://github.com/AntelopeIO/cdt/releases) for current information on releases, pre-releases, and obsolete releases as well as the corresponding tags for those releases.
+## Binary packages
+
+CDT currently supports Linux x86_64 Debian packages. Visit the [release page](https://github.com/AntelopeIO/cdt/releases) to download the package for the appropriate version of CDT. This is the fastest way to get started with the software.
+### Debian package install
+
+The latest version of CDT is 3.0. Download the appropriate version of the Debian package and then install as follows:

-## Binary Releases
-CDT currently supports Linux x86_64 Debian packages.
-### Debian Package Install
 ```sh
 wget https://github.com/AntelopeIO/cdt/releases/download/v3.0.0-rc1/cdt_3.0.0-rc1_amd64.deb
 sudo apt install ./cdt_3.0.0-rc1_amd64.deb
 ```
-### Debian Package Uninstall
+### Debian package uninstall
+
+To remove CDT that was installed using a Debian package, simply execute the following command:
+
 ```sh
 sudo apt remove cdt
 ```

-## Building
+## Building from source
+
+Recent Ubuntu LTS releases are the only Linux distributions that we fully support. Other Linux distros and other POSIX operating systems (such as macOS) are tended to on a best-effort basis and may not be full featured. 
+
+The instructions below assume that you are building on Ubuntu 20.04. 
+
+### Install dependencies

-### Ubuntu 20.04 dependencies
 ```sh
 apt-get update && apt-get install   \
        build-essential             \
@@ -30,62 +46,114 @@ apt-get update && apt-get install   \
        python3-pip                 \
        time
 ```
+
 ```sh
 python3 -m pip install pygments
 ```

-If issues persist with ccache
+### Allowing integration tests to build
+
+Integration tests require access to a build of [Leap](https://github.com/AntelopeIO/leap), a C++ implementation of the Antelope protocol. Simply installing Leap from a binary package will not be sufficient.
+
+If you do not wish to build Leap, you can continue with building CDT but without building the integration tests. Otherwise, follow the instructions below before running `cmake`.
+
+First, ensure that Leap has been built from source (see Leap's [README](https://github.com/AntelopeIO/leap#building-from-source) for details) and identify the build path, e.g. `/path/to/leap/build/`.
+
+Then, execute the following command in the same terminal session that you will use to build CDT:
+
+```sh
+export leap_DIR=/path/to/leap/build/lib/cmake/leap
+```
+
+Now you can continue with the steps to build CDT as described. When you run `cmake` make sure that it does not report `leap package not found`. If it does, this means CDT was not able to find a build of Leap at the specified path in `leap_DIR` and will therefore continue without building the integration tests.
+
+### ccache
+
+If issues persist with ccache when building CDT, you can disable ccache:
+
 ```sh
 export CCACHE_DISABLE=1
 ```

-### Building Integration Tests
+### Build CDT

-Integration tests require access to a Leap build.  Instructions below provide additional steps for using a Leap built from source.  For development purposes it is generally advised to use Leap built from source.
+**A Warning On Parallel Compilation Jobs (`-j` flag)**: When building C/C++ software often the build is performed in parallel via a command such as `make -j $(nproc)` which uses the number of CPU cores as the number of compilation jobs to perform simultaneously. However, be aware that some compilation units (.cpp files) in CDT are extremely complex and can consume a large amount of memory to compile. If you are running into issues due to amount of memory available on your build host, you may need to reduce the level of parallelization used for the build. For example, instead of `make -j $(nproc)` you can try `make -j2`. Failures due to memory exhaustion will typically but not always manifest as compiler crashes.

-#### For building integration tests with Leap built from source
-
-Set an environment variable to tell CDT where to find the Leap build directory:
-
-```sh
-export eosio_DIR=/path/to/leap/build/lib/cmake/eosio
-export leap_DIR=/path/to/leap/build/lib/cmake/leap
-```
-
-### Guided Installation or Building from Scratch
 ```sh
 git clone --recursive https://github.com/AntelopeIO/cdt
 cd cdt
 mkdir build
 cd build
 cmake ..
-make -j8
+make -j $(nproc)
 ```

-From here onward you can build your contracts code by simply exporting the `build` directory to your path, so you don't have to install globally (makes things cleaner).
-Or you can install globally by running this command:
+The binaries will be located at in the `build/bin` directory. You can export the path to the directory to your `PATH` environment variable which allows you to conveniently use them to compile contracts without installing CDT globally. Alternatively, you can use CMake toolchain file located in `build/lib/cmake/CDTWasmToolchain.cmake` to compile the contracts in your CMake project, which also allows you to avoid installing CDT globally.

-```sh
-sudo make install
-```
+If you would prefer to install CDT globally, see the section [Install CDT](#install-cdt) below.

-### Running Tests
+### Run tests
+
+#### Run unit tests

-#### Unit Tests
 ```sh
 cd build

 ctest
 ```

-#### Running Integration Tests (if built)
+#### Run integration tests (if built)
+
 ```sh
 cd build/tests/integration

 ctest
 ```

-### Uninstall after manual installation
+### Install CDT
+
+Installing CDT globally on your system will install the following tools in a location accessible to your `PATH`:
+
+* cdt-abidiff
+* cdt-ar
+* cdt-cc
+* cdt-cpp
+* cdt-init
+* cdt-ld
+* cdt-nm
+* cdt-objcopy
+* cdt-objdump
+* cdt-ranlib
+* cdt-readelf
+* cdt-strip
+* eosio-pp
+* eosio-wasm2wast
+* eosio-wast2wasm 
+
+It will also install CMake files for CDT accessible within a `cmake/cdt` directory located within your system's `lib` directory.
+#### Manual installation
+
+One option for installing CDT globally is via `make install`. From within the `build` directory, run the following command:
+
+```
+sudo make install
+```
+
+#### Package installation
+
+A better option for installing CDT globally is to generate a package and then install the package. This makes uninstalling CDT much easier.
+
+From within the `build` directory, run the following commands to generate a Debian package:
+
+```sh
+cd packages
+bash ./generate_package.sh deb ubuntu-20.04 amd64
+sudo apt install ./cdt_*_amd64.deb
+```
+
+### Uninstall CDT
+
+#### Uninstall CDT after manual installation with make

 ```sh
 sudo rm -fr /usr/local/cdt
@@ -94,19 +162,11 @@ sudo rm /usr/local/bin/eosio-*
 sudo rm /usr/local/bin/cdt-*
 ```

-## Installed Tools
---
-* cdt-cpp
-* cdt-cc
-* cdt-ld
-* cdt-init
-* cdt-abidiff
-* cdt-wasm2wast
-* cdt-wast2wasm
-* cdt-ranlib
-* cdt-ar
-* cdt-objdump
-* cdt-readelf
+#### Uninstall CDT that was installed using a Debian package
+
+```sh
+sudo apt remove cdt
+```

 ## License

@@ -6,7 +6,7 @@ ExternalProject_Add(
  CDTWasmTests
  SOURCE_DIR "${CMAKE_SOURCE_DIR}/tests/unit"
  BINARY_DIR "${CMAKE_BINARY_DIR}/tests/unit"
-  CMAKE_ARGS -DCMAKE_TOOLCHAIN_FILE=${CMAKE_BINARY_DIR}/lib/cmake/cdt/CDTWasmToolchain.cmake -DCMAKE_BUILD_TYPE=Release -DCDT_BIN=${CMAKE_BINARY_DIR}/lib/cmake/cdt/ -DBASE_BINARY_DIR=${CMAKE_BINARY_DIR} -D__APPLE=${APPLE} -DCMAKE_MODULE_PATH=${CMAKE_MODULE_PATH} -DCMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH} -Dleap_DIR=${leap_DIR}
+  CMAKE_ARGS -DCMAKE_TOOLCHAIN_FILE=${CMAKE_BINARY_DIR}/lib/cmake/cdt/CDTWasmToolchain.cmake -DCMAKE_BUILD_TYPE=Release -DCDT_BIN=${CMAKE_BINARY_DIR}/lib/cmake/cdt/ -DBASE_BINARY_DIR=${CMAKE_BINARY_DIR} -D__APPLE=${APPLE} -DCMAKE_MODULE_PATH=${CMAKE_MODULE_PATH} -DCMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH}
  UPDATE_COMMAND ""
  PATCH_COMMAND  ""
  TEST_COMMAND   ""
@@ -16,7 +16,7 @@ VERSION_SUFFIX="@VERSION_SUFFIX@"
 VERSION="@VERSION_FULL@"

 # Using CMAKE_BINARY_DIR uses an absolute path and will break cross-vm building/download/make functionality
-BUILD_DIR="../../build"
+BUILD_DIR="../"

 VENDOR="@VENDOR@"
 PROJECT="@PROJECT_NAME@"
@@ -49,7 +49,7 @@ fi
 # make symlinks
 pushd ${PREFIX}/lib/cmake/${PROJECT} &> /dev/null
 ln -sf ../../../${SUBPREFIX}/lib/cmake/${PROJECT}/${PROJECT}-config.cmake ${PROJECT}-config.cmake || exit 1
-ln -sf ../../../${SUBPREFIX}/lib/cmake/${PROJECT}/CDTToolchain.cmake CDTWasmToolchain.cmake || exit 1
+ln -sf ../../../${SUBPREFIX}/lib/cmake/${PROJECT}/CDTWasmToolchain.cmake CDTWasmToolchain.cmake || exit 1
 ln -sf ../../../${SUBPREFIX}/lib/cmake/${PROJECT}/CDTMacros.cmake CDTMacros.cmake || exit 1
 popd &> /dev/null