# Compiling code in notebook cells

Compile and run C, C++, CUDA, Fortran and Rust code, or run JavaScript and TypeScript, straight from a notebook cell with Eugo's cell magics: which sessions have them, how a cell runs, every option, and an example of each.

Source: https://docs.eugo.io/docs/guides/compile-cells/

---

A notebook cell in EugoIDE can hold code in a language other than Python. Start the cell with a cell magic, a first line that begins with `%%`, and Eugo writes the rest of the cell to a file, compiles it, runs the program and shows what it printed under the cell:

| Magic | Language | Runs with |
| --- | --- | --- |
| `%%clang++` | C++ | `clang++` |
| `%%clang` | C | `clang` |
| `%%cu++` | CUDA | `clang++` in CUDA mode, linked against the CUDA runtime |
| `%%fortran` | Fortran (free form) | `flang` |
| `%%rust` | Rust | `rustc` |
| `%%node` | JavaScript (ES modules) | `node` |
| `%%typescript`, or its short form `%%ts` | TypeScript | `node`, which removes the types itself, with no separate `tsc` step |

The rest of the notebook stays Python: a magic applies only to the cell it starts, so Python cells and magic cells can sit side by side.

> **Note:** Every output on this page was captured by running the cells in a real notebook kernel in Eugo images. Compiler versions and timings change from one image to the next, so run the same cells in your own session to see yours. In the Extended session the compilers also print a detailed report of each compile under the cell: the compiler's version, its configuration files, the folders it searches and the full commands it runs. The outputs on this page leave that report out; anything else left out is named where it happens.

## Which sessions have which magics

`%%node`, `%%typescript` and `%%ts` are available in every EugoIDE session.

`%%clang++`, `%%clang`, `%%cu++`, `%%fortran` and `%%rust` need compilers that ship only in the **Eugo C/C++/CUDA Extended** session option, which you pick when you start your session. That option is part of the Enterprise plan; on the other plans it is shown when you start a session, but locked. In any other session the compiled magics do not exist, and a cell that starts with one fails with IPython's own message:

```text
UsageError: Cell magic `%%clang++` not found.
```

A magic cell runs inside your notebook session, on the session's own CPUs and memory. It does not run on your Ray cluster.

## How a magic cell runs

1. Eugo writes the cell, without its first line, to a file in `/tmp/eugo_magics/`. The file name is a hash of the compiler, the options and the code, followed by the language's usual extension: `.cc`, `.c`, `.cu`, `.f90`, `.rs`, `.mjs` or `.mts`.
2. For the compiled magics, the compiler builds a program from that file and Eugo runs it. Everything the program prints on standard output or standard error appears under the cell. Compiler warnings appear under the cell when it compiles; a cached rerun (item 3) does not show them again. For `%%node`, `%%typescript` and `%%ts`, `node` runs the file itself.
3. Running the same cell again with the same options reuses the program built the first time instead of compiling again; with `-t`, the compile time then reads `[cached]`. Changing the code or any compile option compiles it again. The arguments you pass with `-a` are not part of that hash, so changing only them reuses the same program. The files live in `/tmp`, so a new session starts with none.
4. `%%clang++`, `%%clang` and `%%cu++` add `-lm` for you, so the C maths library links with no extra option. `%%cu++` also points `clang++` at the CUDA toolkit and links the CUDA runtime library.
5. `-a` splits its value at spaces, and quote marks around the value stay on its first and last word: `-a "hello world"` passes two arguments, `"hello` and `world"`, as the C and JavaScript examples below show.
6. If the code does not compile, or the program exits with a code other than 0, the cell is marked as failed: the compiler's messages or the program's output come first, and the cell ends with an error that names what failed. A `%%cu++` cell that fails also runs NVIDIA's `nvidia-smi` tool and prints what it reports, which shows whether the session can see a GPU. In a session without a GPU that line reads `[cu++ diagnostics] nvidia-smi not found in PATH — likely no NVIDIA driver on this node.`
7. There is no time limit: a cell runs until its program ends. To stop one, interrupt the kernel. To set a limit, set `EUGO_MAGIC_RUN_TIMEOUT_SECONDS` to a number of seconds, for example with `%env EUGO_MAGIC_RUN_TIMEOUT_SECONDS=600`. It is read each time a cell runs, so it takes effect at once, and setting it to an empty value removes the limit again. A program that runs past the limit is stopped. For `%%clang++`, `%%clang`, `%%cu++`, `%%fortran` and `%%rust`, the cell shows what the program printed before that, then the time-out line. For `%%node`, `%%typescript` and `%%ts`, the cell shows only the time-out line and the error: what the program printed before the limit is not shown. [Failures and time limits](#failures-and-time-limits) shows each case.

## Options

Options go on the magic's first line, after its name. An option that takes a value takes it as the next word (`-O 2`, `-s c++23`), and an option that "May be repeated" is given once per value (`-l foo -l bar`). A value that itself starts with `-`, such as a compiler flag, must be joined to its option with `=`: write `--extra-cflag=-Wall`. Written as two words, `--extra-cflag -Wall` stops the cell with this message:

```text
UsageError: argument --extra-cflag: expected one argument
```

The descriptions in the tables are the magics' own help texts. To read a magic's help in your session, run a cell that holds only the magic's name followed by `?`, for example `%%rust?`.

### Options for C, C++, CUDA and Fortran

`%%clang++`, `%%clang`, `%%cu++` and `%%fortran` share one set of options:

| Option | Help text |
| --- | --- |
| `-s`, `--std` | -std= value (e.g. c++23, c17, f2018). Default: whatever the upstream driver picks. |
| `-O`, `--optimize` | Optimization level: 0, 1, 2, 3, s, z, g. |
| `-I`, `--include` | Add include path. May be repeated. |
| `-l`, `--lib` | Link library (`-l<lib>`). May be repeated. |
| `-L`, `--libdir` | Library search path (`-L<dir>`). May be repeated. |
| `-D`, `--define` | Preprocessor define (`-D<name>[=<value>]`). May be repeated. |
| `-a`, `--args` | Runtime args passed to the compiled binary. |
| `-t`, `--time` | Print wall-clock time of compile + run. |
| `-k`, `--keep` | Print the compiled binary path so the user can inspect it. |
| `--format` | Run clang-format on the cell body before compile. |
| `--extra-cflag` | Raw extra flag forwarded verbatim to the compiler. Use sparingly. |

### Options for Rust

`%%rust` uses `rustc`'s own flag names, so its options differ: `--edition` instead of `-s`, `--opt-level` instead of `-O`, and no `-I`, `-D` or `--format`.

| Option | Help text |
| --- | --- |
| `--edition` | Rust edition (e.g. 2015, 2018, 2021, 2024). Default: rustc's default. |
| `--opt-level` | Optimization level: 0, 1, 2, 3, s, z. Translates to `-C opt-level=`. |
| `-l`, `--lib` | Link library (`-l<lib>`). May be repeated. |
| `-L`, `--libdir` | Library search path (`-L<dir>`). May be repeated. |
| `--extern` | External crate (`--extern name=path`). May be repeated. |
| `--cfg` | cfg flag (`--cfg <spec>`, e.g. `feature="x"`). May be repeated. |
| `-a`, `--args` | Runtime args passed to the compiled binary. |
| `-t`, `--time` | Print wall-clock time of compile + run. |
| `-k`, `--keep` | Print the compiled binary path so the user can inspect it. |
| `--extra-rustflag` | Raw extra flag forwarded verbatim to rustc. Use sparingly. |

### Options for JavaScript and TypeScript

`%%node`, `%%typescript` and `%%ts` share these options:

| Option | Help text |
| --- | --- |
| `-a`, `--args` | Runtime args passed to the script (process.argv). |
| `-t`, `--time` | Print wall-clock run time. |
| `-k`, `--keep` | Print the written script path so the user can inspect it. |
| `--extra-node-flag` | Raw extra flag forwarded verbatim to `node`. Use sparingly. |

## Examples

### C++ with the clang++ magic

```cpp
%%clang++ -s c++23 -O 2
#include <iostream>
#include <numeric>
#include <vector>

int main() {
    std::vector<int> v{1, 2, 3, 4, 5};
    std::cout << "sum = " << std::accumulate(v.begin(), v.end(), 0) << '\n';
}
```

The cell prints:

```text
sum = 15
```

### C with the clang magic

```c
%%clang -a "hello world"
#include <stdio.h>

int main(int argc, char **argv) {
    for (int i = 1; i < argc; ++i)
        printf("argument %d: %s\n", i, argv[i]);
    return 0;
}
```

The program receives two arguments, and the quote marks stay on them:

```text
argument 1: "hello
argument 2: world"
```

### Passing a compiler flag

`--extra-cflag=-Wall` passes `-Wall` to the compiler, which turns on its common warnings. `-t` prints how long the compile and the run took, and `-k` prints where the program was saved:

```c
%%clang --extra-cflag=-Wall -t -k
#include <stdio.h>

int main(void) {
    int unused = 0;
    printf("built with -Wall\n");
    return 0;
}
```

The program's own line can appear above the compiler's warning, as it does here:

```text
built with -Wall
/tmp/eugo_magics/10b146cf4797cac1.c:4:9: warning: unused variable 'unused' [-Wunused-variable]
    4 |     int unused = 0;
      |         ^~~~~~
1 warning generated.
[compile] 1.400s
[binary] /tmp/eugo_magics/10b146cf4797cac1.bin
[run] 0.005s
```

### CUDA with the cu++ magic

Your EugoIDE session has no GPU: the GPUs are in your cluster's GPU worker pools. The cell below adds two vectors on a GPU. It checks for a GPU first and exits with an error when it finds none.

The cell is shown without output, because in a session it does not get that far: today a `%%cu++` cell with no options does not compile. By default the compiler builds for an older type of GPU than the CUDA toolkit in the session supports, and the compile stops with this line among the compiler's messages:

```text
ptxas fatal   : Value 'sm_52' is not defined for option 'gpu-name'
```

The cell then shows the `nvidia-smi` line described in [How a magic cell runs](#how-a-magic-cell-runs), and ends with the compile-failed error, `_EugoMagicError: [%%cu++] compile failed; see clang diagnostics above.`

To build for a GPU type the toolkit supports, name it with `--offload-arch`, for example `%%cu++ --extra-cflag=--offload-arch=sm_75` as the cell's first line. With that line the same cell compiles. In a session it then stops at its own check: it prints `no GPU is visible here`, the cell shows the `nvidia-smi` line, and it ends with `_EugoMagicError: [%%cu++] binary exited with code 1; see output above.`

```cpp
%%cu++
#include <cstdio>

__global__ void add(const float* a, const float* b, float* c, int n) {
    int i = blockIdx.x * blockDim.x + threadIdx.x;
    if (i < n) c[i] = a[i] + b[i];
}

int main() {
    int devices = 0;
    if (cudaGetDeviceCount(&devices) != cudaSuccess || devices == 0) {
        std::fprintf(stderr, "no GPU is visible here\n");
        return 1;
    }

    constexpr int N = 8;
    float a[N], b[N], c[N];
    for (int i = 0; i < N; ++i) { a[i] = float(i); b[i] = float(2 * i); }

    float *da, *db, *dc;
    cudaMalloc(&da, N * sizeof(float));
    cudaMalloc(&db, N * sizeof(float));
    cudaMalloc(&dc, N * sizeof(float));
    cudaMemcpy(da, a, N * sizeof(float), cudaMemcpyHostToDevice);
    cudaMemcpy(db, b, N * sizeof(float), cudaMemcpyHostToDevice);

    add<<<1, N>>>(da, db, dc, N);
    cudaMemcpy(c, dc, N * sizeof(float), cudaMemcpyDeviceToHost);

    for (int i = 0; i < N; ++i) std::printf("c[%d] = %.1f\n", i, c[i]);
    cudaFree(da); cudaFree(db); cudaFree(dc);
    return 0;
}
```

### Fortran with the fortran magic

```fortran
%%fortran -s f2018
program hello
  implicit none
  integer :: i
  integer, parameter :: n = 5
  integer :: v(n)

  do i = 1, n
    v(i) = i * i
  end do
  print *, "sum of squares =", sum(v)
end program hello
```

The cell prints the line below. Its leading space comes from Fortran's `print *`:

```text
 sum of squares = 55
```

### Rust with the rust magic

```rust
%%rust --edition 2021 --opt-level 3 -t
fn main() {
    let v: Vec<i32> = (1..=5).collect();
    println!("sum = {}", v.iter().sum::<i32>());
}
```

`rustc` passes the compile report described at the top of this page on as a block that starts with `warning: linker stderr:`. The output below leaves that block out:

```text
sum = 15
[compile] 1.174s
[run] 0.003s
```

Run the same cell a second time and the program is not built again, so `-t` shows the compile time as `[cached]`:

```text
sum = 15
[compile] 0.000s [cached]
[run] 0.003s
```

### JavaScript with the node magic

```javascript
%%node -a "alpha beta"
const words = process.argv.slice(2);
console.log(`node ${process.version} got ${words.length} arguments: ${words.join(", ")}`);
```

As with the compiled magics, the quote marks stay on the first and last word:

```text
node v24.18.0 got 2 arguments: "alpha, beta"
```

### TypeScript with the typescript magic

```typescript
%%typescript
enum Color { Red, Green, Blue }

function describe(c: Color): string {
  return `${Color[c]} is ${c}`;
}

console.log(describe(Color.Green));
```

The cell prints:

```text
Green is 1
```

`%%ts` is the same magic under a shorter name:

```typescript
%%ts -t
const squares: number[] = [1, 2, 3, 4].map((n: number) => n * n);
console.log(squares);
```

The cell prints:

```text
[ 1, 4, 9, 16 ]
[run] 0.559s
```

## Failures and time limits

### Code that does not compile

```cpp
%%clang++
#include <string>

int main() {
    std::string s = 42;
    return 0;
}
```

The compiler's error comes first, and the cell ends with the magic's own error. The compiler also lists the `std::string` constructors it tried; this output leaves those out:

```text
/tmp/eugo_magics/6fd99b0bf01259fe.cc:4:17: error: no viable conversion from 'int' to 'std::string' (aka 'basic_string<char>')
    4 |     std::string s = 42;
      |                 ^   ~~
1 error generated.
_EugoMagicError: [%%clang++] compile failed; see clang diagnostics above.
```

### A program that exits with an error

```c
%%clang
#include <stdio.h>

int main(void) {
    fprintf(stderr, "input file not found\n");
    return 3;
}
```

The program's message comes first, and the cell ends with an error that gives the exit code:

```text
input file not found
_EugoMagicError: [%%clang] binary exited with code 3; see output above.
```

### A program that runs past the time limit

```python
%env EUGO_MAGIC_RUN_TIMEOUT_SECONDS=2
```

```text
env: EUGO_MAGIC_RUN_TIMEOUT_SECONDS=2
```

```c
%%clang
#include <stdio.h>
#include <unistd.h>

int main(void) {
    printf("working...\n");
    fflush(stdout);
    sleep(10);
    printf("done\n");
    return 0;
}
```

The program is stopped after 2 seconds, so its second line never appears. The cell shows what it printed before that, the time-out line, and an error naming the time-out:

```text
working...
[run] timed out after 2s; killed.
TimeoutExpired: Command '['/tmp/eugo_magics/9ed6313fdd9d4a68.bin']' timed out after 2.0 seconds
```

To remove the limit again:

```python
%env EUGO_MAGIC_RUN_TIMEOUT_SECONDS=
```

```text
env: EUGO_MAGIC_RUN_TIMEOUT_SECONDS=
```

## Related pages

- [Installing Python packages](./installing-python-packages.md) covers adding Python packages to your session and to your Ray cluster. The magics on this page compile against what is already in your session.
- [EugoHPC Manager](./hpc-cluster-manager.md) covers your Ray clusters. Magic cells run in your notebook session, not on a cluster.
- To build larger C, C++ and Fortran projects from the terminal rather than from a notebook cell, see the guide "Compiling your own C, C++ and Fortran code in Eugo".
