From 8e2d3e2c2b74d7fe2db10b1a024db9fe897570be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20Storsj=C3=B6?= Date: Tue, 28 Nov 2017 15:12:45 +0200 Subject: [PATCH] Add an initial readme for github --- README.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..41a5c83 --- /dev/null +++ b/README.md @@ -0,0 +1,89 @@ +LLVM MinGW +========== + +This is a recipe for reproducibly building a +[LLVM](https://llvm.org)/[Clang](https://clang.llvm.org/)/[LLD](https://lld.llvm.org/) +based mingw-w64 toolchain. + +Benefits of a LLVM based MinGW toolchain are: +- Support for targeting ARM/ARM64 (while GCC obviously does support + these architectures, it doesn't support Windows on ARM) +- A single toolchain targeting all four architectures (i686, x86_64, + armv7 and arm64) instead of separate compiler binaries for each + architecture + +Clang on its own can also be used as compiler in the normal GNU binutils +based environments though, so the main difference lies in replacing +binutils with LLVM based tools. + +This is similar to https://github.com/martell/mingw-w64-clang, with +the exact same goal but with a slightly different mechanism for +building it, allowing a full from-scratch build of all components +in one command. + +The only prerequisite for building is Docker; you can also follow the +steps of the Dockerfile and build manually within a normal linux +environment, but Docker provides reproducibility by building in a known, +empty environment. + +To build, just do: + + docker build . + +This will download and build all parts of the toolchain, and build a few +demo apps to show and verify that the toolchain works. + +The produced toolchain can be extracted by running this command with the +image id from the `docker build` command above (ending with e.g. +`Successfully built d8b13aad965a`): + + ./extract-docker.sh d8b13aad965a prefix + +This copies the directory `prefix` (which contains the whole toolchain, +with headers and link libraries for all four architectures) from the +built docker image into the current directory. +The Dockerfile currently builds in an Ubuntu 16.04 environment, so the +extracted toolchain can at least be used in such an environment. + +The extracted toolchain can be used by adding `prefix/bin` to `$PATH` +and calling e.g. `x86_64-w64-ming32-clang`. +(If using the extracted toolchain in an environment that already have +got a normal GCC based MinGW toolchain with the same triplet prefix in +the same path, you may need to add +`--sysroot=path/to/prefix/x86_64-w64-mingw32` to the clang commands.) + +Other branches in this repo contain patches that might not have been +merged upstream yet, and tests of building third party projects using +the toolchain. This includes more tool frontends/wrappers with the +usual binutils names, to allow using it as a drop-in replacement for +a normal MinGW toolchain. + + +Status +------ + +The toolchain currently does support both C and C++, including support +for exception handling. + +It is in practice quite new and immature and haven't been proven with a +large number of projects yet though. You will probably run into issues +building non-trivial projects. + + +Known issues +------------ + +LLD, the LLVM linker, is what causes most of the major differences to the +normal GCC/binutils based MinGW. + +- LLD doesn't support using import libraries created by GNU tools. +- LLD doesn't automatically fix up use of data symbols from DLLs without + the dllimport attributes. +- The C++ libraries ([libcxxabi](http://libcxxabi.llvm.org/), [libcxx](http://libcxx.llvm.org/)) can only be linked statically + at the moment. +- The C++ libraries and unwinder aren't built with exceptions support for + ARM64 target at the moment. (The toolchain and libraries themselves do + support it though.) +- The ARM64 target doesn't support thread local variables. + +Additionally, one may run into other minor differences between GCC and clang.