compiler/rustc_codegen_cranelift/docs/usage.md

   1 # Usage
   2
   3 rustc_codegen_cranelift can be used as a near-drop-in replacement for `cargo build` or `cargo run` for existing projects.
   4
   5 Assuming `$cg_clif_dir` is the directory you cloned this repo into and you followed the instructions (`prepare.sh` and `build.sh` or `test.sh`).
   6
   7 ## Cargo
   8
   9 In the directory with your project (where you can do the usual `cargo build`), run:
  10
  11 ```bash
  12 $ $cg_clif_dir/build/cargo.sh build
  13 ```
  14
  15 This will build your project with rustc_codegen_cranelift instead of the usual LLVM backend.
  16
  17 ## Rustc
  18
  19 > You should prefer using the Cargo method.
  20
  21 ```bash
  22 $ $cg_clif_dir/build/bin/cg_clif my_crate.rs
  23 ```
  24
  25 ## Jit mode
  26
  27 In jit mode cg_clif will immediately execute your code without creating an executable file.
  28
  29 > This requires all dependencies to be available as dynamic library.
  30 > The jit mode will probably need cargo integration to make this possible.
  31
  32 ```bash
  33 $ $cg_clif_dir/build/cargo.sh jit
  34 ```
  35
  36 or
  37
  38 ```bash
  39 $ $cg_clif_dir/build/bin/cg_clif -Cllvm-args=mode=jit -Cprefer-dynamic my_crate.rs
  40 ```
  41
  42 There is also an experimental lazy jit mode. In this mode functions are only compiled once they are
  43 first called. It currently does not work with multi-threaded programs. When a not yet compiled
  44 function is called from another thread than the main thread, you will get an ICE.
  45
  46 ```bash
  47 $ $cg_clif_dir/build/cargo.sh lazy-jit
  48 ```
  49
  50 ## Shell
  51
  52 These are a few functions that allow you to easily run rust code from the shell using cg_clif as jit.
  53
  54 ```bash
  55 function jit_naked() {
  56     echo "$@" | $cg_clif_dir/build/bin/cg_clif - -Cllvm-args=mode=jit -Cprefer-dynamic
  57 }
  58
  59 function jit() {
  60     jit_naked "fn main() { $@ }"
  61 }
  62
  63 function jit_calc() {
  64     jit 'println!("0x{:x}", ' $@ ');';
  65 }
  66 ```