C and C++ compiler for TVM
Clang for TVM based on LLVM 7.0.0. This repository contain
- Clang for TVM C and C++ compiler
- C++ runtime and SDK headers-only library
- C runtime and SDK library The following guide is about building the compilers and installing them, to find a user guide and example contracts, please refer to the samples repository.
To build the toolchain, you need a recent C++ toolchain supporting C++17:
- MSVC 2017 or newer
- Clang 6.0.0 or newer
- GCC 7.3.0 or newer Stable operation of older toolchains is not guaranteed. You also need zlib 184.108.40.206 or newer. Python 2.7 is required to run tests. Optionally, you can use ninja-build. For more info about LLVM software requirements visit: https://llvm.org/docs/GettingStarted.html.
Supported operation systems
We expect the project to build successfully on
- Ubuntu 16.04, 18.04
- Mac OS Mojave 10.14.3 or higher
- Windows 10
Building and installing
To build and to install the compiler use the following script:
$ git clone email@example.com:tonlabs/TON-Compiler.git $ mkdir build $ cd build $ cmake -DCMAKE_INSTALL_PREFIX=/path/to/install -C /path/to/TON-Compiler/cmake/Cache/ton-compiler.cmake $ cmake --build . --target install-distribution
/path/to/installmust be complete path to the installation folder, otherwise Clang might be unable to find all the libraries, headers and tools by default.
- We strongly recommend to use the installed version of the compiler, otherwise it might be unable to find the required headers and tools by itself, so they have to be specified by hands.
- A complete C and C++ toolchain require tvm_linker to be built. We recommend to put the liker binary to
/path/to/install/bindirectory. Otherwise you might need to use
-fuse-ldoption to spicify full name of the linker.
install-distributioninstalls only required minimum of tools, while
installtarget copies all the LLVM tools to the installation folder. These additional tools doesn't necessary work with TVM target properly.
Troubleshooting and speeding up the build
Building Clang takes quite a bit of time, below we list some options to speed it up:
- Use faster build system via
-GXXXoption. We recommend to choose
ninja-build(you might need to install it first) using
- Use a faster linker via
-DCMAKE_LINKER=<linker name>. It's known that
lldis faster than
gold, and gold is faster than
ld. On Linux, however,
lldmight not be a part of the default toolchain, so you might have to install it first.
- Use a faster compiler via
-DCMAKE_CXX_COMPILER=<compiler>. Clang might be slightly faster than GCC.
- Build dynamically linked version of Clang via
-DBUILD_SHARED_LIB=On. Note that building Clang also require a tens of gigabytes of disk space (especially for a static build) and several gigabytes of RAM to be build. In case, you run out of memory
-DLLVM_PARALLEL_LINK_JOBS=Nmight be of help. This option limits the number of link jobs running in parallel does the footpring. There is also a separate option
-DLLVM_PARALLEL_COMPILE_JOBS=Nto limit number of compilation jobs running in parallel. To learn more about possible configurations of LLVM build, please refer to LLVM documentation. In case you are experiencing problems with build, we would appreciete raising an issue in this repository.
To run tests for TVM, execute
$ cmake --build . --target check-llvm-codegen-tvm
To run tests for other platforms (to ensure that LLVM itself is not broken), you have to create a separate build without using
/path/to/TON-Compiler/cmake/Cache/ton-compiler.cmake config and run
$ cmake --build . --target check all
For more details see testing.md.
Example of usage
You can learn more about C++ for TVM and find examples of usage of C++ toolchain here. C toolchain is mostly for geeks who want to follow TVM assembly closely, but doesn't want to work with stack. C examples might be found here.
C and C++ for TVM, being similar to conventional C and C++, has their own extensions and limitations, so if you are getting started with programming for TVM, we recommend to first refer to the examples repository. Texts, videos and samples illustrating how to use the compiler will soon appear at https://ton.dev/ and https://www.youtube.com/channel/UC9kJ6DKaxSxk6T3lEGdq-Gg. Stay tuned. You can also get support in TON Dev Telegram channel. In case you found a bug, raise an issue in the repository. Please attach the source file, the command to reproduce the failure and your machine description.
The project strives to follow LLVM coding standards and policies as well as C++ Core Guidelines, so before contributing, we recommend you to familiarize with the following documents:
Note: Since TVM backend uses C++17 which is not yet fully supported in LLVM, the guidelines could be reasonably adjusted for cases of C++17 usages. C++17 data structures are preferred over LLVM counterparts, for instance,
std::optional<T> is better to use w.r.t.
All changes in LLVM (excluding
lib/Target/TVM subdirectory) must be marked as local changes in the following way:
// TVM local begin <changed LLVM code> // TVM local end
The reason is to help resolving merge conflicts when updating LLVM to a new version.
All removals from LLVM must be commented out instead:
#if 0 <removed LLVM code> #endif
The reason is to minimize number of merge conflicts when updating LLVM to a new version. To learn more about development a downstream LLVM project, refer to https://llvm.org/devmtg/2015-10/slides/RobinsonEdwards-LivingDownstreamWithoutDrowning.pdf.
We believe that LLVM community would benefit from getting TVM backend upstream. It's a very distinct architecture, that break several assumptions. For instance, Clang front-end and the optimizer relies on 8-bit bytes byte which is not true for TVM as well as for some non-mainstream processors. Furthermore, target independent code generator is designed for a register machine, so stack machine support is benefitial at least for WebAssembly. So, with some constraints removed, LLVM will be better placed to downstream development and we believe it is feasible without damaging existing targets. We would like to implement, upstream and maintain the following features:
- Byte size specified in data layout, removing magical number 8 from the optimizer.
- memset, memcopy, memmove configured with the byte size.
- DAG scheduler for a stack machine.
- Generic analysis and transformation passes to optimize for stack machine on MIR level. The current version of Clang for TVM is based on LLVM 7.0.0, it's planned update LLVM, remove hardcoded byte size and adopt opaque types insted of types we introduced to LLVM.