gcc/rust/README.md

   1 ![C/C++ CI](https://github.com/Rust-GCC/gccrs/workflows/C/C++%20CI/badge.svg)
   2 [![GCC Bootstrap Build](https://github.com/Rust-GCC/gccrs/actions/workflows/bootstrap.yml/badge.svg)](https://github.com/Rust-GCC/gccrs/actions/workflows/bootstrap.yml)
   3 [![Build Docker image](https://github.com/Rust-GCC/gccrs/actions/workflows/docker.yml/badge.svg)](https://github.com/Rust-GCC/gccrs/actions/workflows/docker.yml)
   4 ![Docker Pulls](https://img.shields.io/docker/pulls/philberty/gccrs)
   5 [![project chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://gcc-rust.zulipchat.com/)
   6 [![Bors enabled](https://bors.tech/images/badge_small.svg)](https://app.bors.tech/repositories/32890)
   7 # GCC Rust
   8 ![GCC Rust](logo.png?raw=true "GCC rust Logo")
   9
  10 Please note, the compiler is in a very early stage and not usable yet for compiling real Rust programs.
  11
  12 gccrs is a full alternative implementation of the Rust language ontop of GCC with the goal
  13 to become fully upstream with the GNU toolchain.
  14
  15 The origin of this project was a community effort several years ago where Rust was still at version 0.9;
  16 the language was subject to so much change that it became difficult for a community effort to play catch up.
  17 Now that the language is stable, it is an excellent time to create alternative compilers. The developers of
  18 the project are keen “Rustaceans” with a desire to give back to the Rust community and to learn what GCC is capable
  19 of when it comes to a modern language.
  20
  21 ## Build Farm Status
  22
  23 - [Debian i386](https://builder.sourceware.org/buildbot/#/builders/gccrust-debian-i386) [![Debian i386](https://builder.sourceware.org/buildbot/badges/gccrust-debian-i386.svg)](https://builder.sourceware.org/buildbot/#/builders/gccrust-debian-i386)
  24 - [Debian ppc64](https://builder.sourceware.org/buildbot/#/builders/gccrust-debian-ppc64) [![Debian ppc64](https://builder.sourceware.org/buildbot/badges/gccrust-debian-ppc64.svg)](https://builder.sourceware.org/buildbot/#/builders/gccrust-debian-ppc64)
  25 - [Debian testing-x86_64](https://builder.sourceware.org/buildbot/#/builders/146) [![Debian testing-x86_64](https://builder.sourceware.org/buildbot/badges/gccrust-debian-testing-x86_64.svg)](https://builder.sourceware.org/buildbot/#/builders/146)
  26 - [Fedora arm64](https://builder.sourceware.org/buildbot/#/builders/179) [![Fedora arm64](https://builder.sourceware.org/buildbot/badges/gccrust-fedora-arm64.svg)](https://builder.sourceware.org/buildbot/#/builders/179)
  27 - [Fedora ppc64le](https://builder.sourceware.org/buildbot/#/builders/gccrust-fedora-ppc64le) [![Fedora ppc64le](https://builder.sourceware.org/buildbot/badges/gccrust-fedora-ppc64le.svg)](https://builder.sourceware.org/buildbot/#/builders/gccrust-fedora-ppc64le)
  28 - [Fedora s390x](https://builder.sourceware.org/buildbot/#/builders/gccrust-fedora-s390x) [![Fedora s390x](https://builder.sourceware.org/buildbot/badges/gccrust-fedora-s390x.svg)](https://builder.sourceware.org/buildbot/#/builders/gccrust-fedora-s390x)
  29 - [Fedora X86_64](https://builder.sourceware.org/buildbot/#/builders/gccrust-fedora-x86_64) [![Fedora X86-64](https://builder.sourceware.org/buildbot/badges/gccrust-fedora-x86_64.svg)](https://builder.sourceware.org/buildbot/#/builders/gccrust-fedora-x86_64)
  30 - [OpenSUSE Leap X86_64](https://builder.sourceware.org/buildbot/#/builders/104) [![OpenSUSE Leap X86_64](https://builder.sourceware.org/buildbot/badges/gccrust-opensuseleap-x86_64.svg)](https://builder.sourceware.org/buildbot/#/builders/104)
  31 - [OpenSUSE tw X86_64](https://builder.sourceware.org/buildbot/#/builders/103) [![OpenSUSE tw X86_64](https://builder.sourceware.org/buildbot/badges/gccrust-opensusetw-x86_64.svg)](https://builder.sourceware.org/buildbot/#/builders/103)
  32 - [Rawhide X86_64](https://builder.sourceware.org/buildbot/#/builders/132) [![Rawhide X86_64](https://builder.sourceware.org/buildbot/badges/gccrust-rawhide-x86_64.svg)](https://builder.sourceware.org/buildbot/#/builders/132)
  33
  34 ## FAQ
  35
  36 Please find the answers to frequently asked questions over on: https://github.com/Rust-GCC/gccrs/wiki/Frequently-Asked-Questions
  37
  38 ## Development Environment
  39
  40 ### Building
  41
  42 Fetch dependencies for Ubuntu:
  43
  44 ```bash
  45 $ apt install build-essential libgmp3-dev libmpfr-dev libmpc-dev flex bison autogen gcc-multilib dejagnu
  46 ```
  47
  48 Clone the repository
  49
  50 ```bash
  51 $ git clone https://github.com/Rust-GCC/gccrs
  52 ```
  53
  54 #### Linux
  55
  56 It is important to remember that GNU toolchain projects are designed to be built outside of their source directory
  57 which is why a build directory is created.
  58
  59 ```bash
  60 $ mkdir gccrs-build
  61 $ cd gccrs-build
  62 $ ../gccrs/configure --prefix=$HOME/gccrs-install --disable-bootstrap --enable-multilib --enable-languages=rust
  63 $ make
  64 ```
  65
  66 #### MacOS
  67
  68 The path of header dir and sysroot should be specified when you configure the project.
  69 ```bash
  70 $ mkdir mac-build
  71 $ cd mac-build
  72 $ ../gccrs/configure --prefix=$HOME/gccrs-install --disable-bootstrap --enable-multilib --enable-languages=rust --with-native-system-header-dir=/usr/include --with-sysroot=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk
  73 $ make
  74
  75 ```
  76
  77 #### Running GCC Rust
  78
  79 Running the compiler itself without make install we can simply invoke the compiler proper:
  80
  81 ```bash
  82 $ ./gcc/rust1 test.rs -frust-debug -frust-dump-parse -Warray-bounds -dumpbase test.rs -mtune=generic -march=x86-64 -O0 -version -fdump-tree-gimple -o test.s -L/lib/x86_64-linux-gnu -L/lib/../lib64 -L/usr/lib/x86_64-linux-gnu -L/usr/lib/../lib64
  83 ```
  84
  85 To invoke the compiler driver (gccrs) we need to:
  86
  87 ```bash
  88 $ make install
  89 ```
  90
  91 Then invoke the compiler from the installation directory:
  92
  93 ```bash
  94 $ $HOME/gccrs-install/gccrs -g -O2 -c test.rs -o test.o
  95 $ $HOME/gccrs-install/gccrs -o test test.o
  96 ```
  97
  98 You can also setup your shell to automatically find the installed compiler. For example for `bash`,
  99 add the following in your `$HOME/.bashrc`:
 100
 101 ```bash
 102 export PATH=$HOME/gccrs-install/bin:$PATH
 103
 104 ```
 105
 106 ## Testsuite
 107
 108 Invoke the full testsuite from the build directory (`gccrs-build` in the previous commands):
 109
 110 ```bash
 111 $ make check-rust
 112 ```
 113
 114 Invoke a subset of the testsuite. For example, to only run tests that are currently known/expected to fail:
 115
 116 ```bash
 117 $ make check-rust RUNTESTFLAGS="xfail.exp"
 118 ```
 119 There are the following sets of tests:
 120 - `compile.exp` : compilation tests
 121 - `execute.exp` : execution tests
 122 - `xfail.exp` : tests that are currently known/expected to fail
 123
 124 Invoke only a specific test :
 125
 126 ```bash
 127 $ make check-rust RUNTESTFLAGS="--all compile.exp=continue1.rs"
 128 ```
 129
 130 Logs (with corresponding commands) can be found in : `gccrs-build/gcc/testsuite/rust/rust.log`.
 131
 132 See [GCC Testing documentation](https://gcc.gnu.org/install/test.html) for more details.
 133
 134 Test cases are located within [`gcc/testsuite/rust/`](gcc/testsuite/rust/).
 135 Please contribute your specific
 136 test cases referencing any issues on Github.
 137
 138 ## Debugging
 139
 140 ### Enabling internal checks
 141
 142 GCC has several internal checks that can be enabled during configuration. In the case of `gccrs`,
 143 you can enable the following:
 144 ```bash
 145 $ ../gccrs/configure --prefix=$HOME/gccrs-install --disable-bootstrap --enable-multilib --enable-languages=rust --enable-checking=gimple,tree,types
 146 ```
 147
 148 ### GDB
 149 You can directly invoke `gdb` on the `rust1` compiler process (you can find the
 150 exact command adding `--verbose` to your `gccrs` invocation):
 151 ```bash
 152 $ gccrs test.rs -O0 -S -o arithmetic_expressions1.s --verbose
 153 ...
 154  /some/path/../../rust1 test.rs -quiet -dumpbase arithmetic_expressions1.rs -dumpbase-ext .rs
 155  -mtune=generic -march=x86-64 -O0 -w -version -fdiagnostics-color=never -fno-diagnostics-show-caret -fno-diagnostics-show-line-numbers -fdiagnostics-urls=never -fdiagnostics-path-format=separate-events -o test.s -L/lib/x86_64-linux-gnu -L/lib/../lib64 -L/usr/lib/x86_64-linux-gnu
 156 ...
 157 $ gdb --args  /some/path/../../rust1 test.rs -quiet -dumpbase arithmetic_expressions1.rs -dumpbase-ext .rs
 158  -mtune=generic -march=x86-64 -O0 -w -version -fdiagnostics-color=never -fno-diagnostics-show-caret -fno-diagnostics-show-line-numbers -fdiagnostics-urls=never -fdiagnostics-path-format=separate-events -o test.s -L/lib/x86_64-linux-gnu -L/lib/../lib64 -L/usr/lib/x86_64-linux-gnu
 159 ```
 160
 161 Or simply add the `-wrapper gdb,--args` option.
 162 This will call each subcommand in `gdb` and you simply have to break/debug in `rust1`:
 163 ```bash
 164 $ gccrs test.rs -O0 -S -o arithmetic_expressions1.s -wrapper gdb,--args
 165 ```
 166
 167 ## Docker image
 168
 169 There is a docker image hosted over on:
 170
 171 https://hub.docker.com/repository/docker/philberty/gccrs
 172
 173 ```bash
 174 $ docker pull philberty/gccrs
 175 ```
 176
 177 Or you can build your own image:
 178
 179 ```bash
 180 $ docker build . -t gccrs-dev
 181 ```
 182 If you want to build an object file:
 183
 184 ```bash
 185 $ docker run --rm -v "$PWD":/usr/src/myapp -w /usr/src/myapp \
 186     gccrs-dev:latest gccrs -g -O2 -c \
 187     gcc/testsuite/rust/compile/torture/type_infer1.rs -o type_infer1.o
 188 ```
 189
 190 If you want to build an executable file:
 191 ```bash
 192 $ docker run --rm -v "$PWD":/usr/src/myapp -w /usr/src/myapp \
 193     gccrs-dev:latest gccrs -g -O2 \
 194     gcc/testsuite/rust/compile/torture/type_infer1.rs -o type_infer1
 195 ```
 196
 197 To emit assembly :
 198 ```bash
 199 $ docker run --rm -v "$PWD":/usr/src/myapp -w /usr/src/myapp \
 200     gccrs-dev:latest gccrs -g -O2 \
 201     gcc/testsuite/rust/compile/torture/type_infer1.rs -S -o type_infer1.s
 202 ```
 203
 204 To emit Rust front end debug output, you may add options like `-frust-debug`, `-frust-dump-all`.
 205
 206
 207 ## Contributing
 208
 209 If you want to contribute to GCC Rust, you can find more information in [CONTRIBUTING.md](https://github.com/Rust-GCC/gccrs/blob/master/CONTRIBUTING.md).
 210
 211 Please be aware this project is designed to be pushed upstream to GCC when we reach some milestones,
 212 and this means we require copyright assignment or the Developer's Certificate of Origin sign-off.
 213 Please see the [Contributing to GCC](https://gcc.gnu.org/contribute.html) guide or [Developer's Certificate of Origin (DCO) Sign-off](https://gcc.gnu.org/dco.html) guide.
 214
 215 Not all contributions must be code; we would love to see new test cases or bugs and issues to be reported.
 216 Feel free to add any comments on open PRs
 217
 218
 219 ## Continuous Integration
 220
 221 When submitting (or updating) a [GitHub Pull Request](https://github.com/Rust-GCC/gccrs/pull/),
 222 several automated checks are run.
 223 Generally, a "green status" is necessary before merge.
 224
 225
 226 ### Compiler Diagnostics
 227
 228 That is, here, diagnostics emitted by the "initial" compiler used to build GCC/Rust.
 229
 230 If building a native toolchain,
 231 GCC by default does a 3-stage bootstrap build (<https://gcc.gnu.org/install/configure.html>).
 232 In addition to making sure that GCC is able to reproduce itself bit-by-bit,
 233 this also means that stages 2+ are built with `-Werror`
 234 (turning most _warning_ into _error_ diagnostics; see `--enable-werror`,
 235 possibly enabled by default).
 236 This helps to catch a good number of bugs, because it enforces that GCC compiles without compiler diagnostics;
 237 it's a requirement for upstream patch submission (<https://gcc.gnu.org/contribute.html#testing>).
 238
 239 GCC generally is only expected to be "warning-clean" without `--disable-bootstrap`
 240 (that is, default `--enable-bootstrap` for a native build),
 241 and not for the initial stage where it's using the "initial" compiler -- otherwise
 242 we're at the mercy of whatever "initial" compiler we're using.
 243 Doing a `--disable-bootstrap` build is much faster, of course, so we're often doing that:
 244 for example, per the instructions above, or in the standard CI.
 245 With that, we're missing out on the aspect that _enforces that GCC compiles without compiler diagnostics_.
 246
 247 To encounter that, the default CI has a [_check for new warnings_ step](https://github.com/Rust-GCC/gccrs/pull/1026)
 248 that verifies in the CI `--disable-bootstrap` build configuration that no new warnings are introduced.
 249 If that step fails, it usually points out a new _warning_ you've introduced erroneously, and should address.
 250 Occasionally it means that simply the `.github/bors_log_expected_warnings` file needs to be updated,
 251 for example if due to any kind of "environmental changes" (for example, CI "initial" compiler changes).
 252 Unless diligently reproducing the CI configuration (in particular "initial" compiler, GCC version),
 253 it's not really feasible to reproduce this check locally.
 254 If in doubt, do a local `--enable-bootstrap` build, or submit your changes, and wait for the CI system's results.
 255
 256
 257 ## Community
 258
 259 We can be found on all usual Rust channels such as Zulip, but we also have our own channels:
 260
 261 * GCC Rust Zulip: https://gcc-rust.zulipchat.com/
 262 * Twitter: https://twitter.com/gcc_rust
 263 * GCC Mailing List: https://gcc.gnu.org/mailman/listinfo/gcc-rust
 264 * irc: irc.oftc.net - gccrust