Skip to main content

Compiling code in notebook 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:

MagicLanguageRuns with
%%clang++C++clang++
%%clangCclang
%%cu++CUDAclang++ in CUDA mode, linked against the CUDA runtime
%%fortranFortran (free form)flang
%%rustRustrustc
%%nodeJavaScript (ES modules)node
%%typescript, or its short form %%tsTypeScriptnode, 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:

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 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:

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:

OptionHelp text
-s, --std-std= value (e.g. c++23, c17, f2018). Default: whatever the upstream driver picks.
-O, --optimizeOptimization level: 0, 1, 2, 3, s, z, g.
-I, --includeAdd include path. May be repeated.
-l, --libLink library (-l<lib>). May be repeated.
-L, --libdirLibrary search path (-L<dir>). May be repeated.
-D, --definePreprocessor define (-D<name>[=<value>]). May be repeated.
-a, --argsRuntime args passed to the compiled binary.
-t, --timePrint wall-clock time of compile + run.
-k, --keepPrint the compiled binary path so the user can inspect it.
--formatRun clang-format on the cell body before compile.
--extra-cflagRaw 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.

OptionHelp text
--editionRust edition (e.g. 2015, 2018, 2021, 2024). Default: rustc's default.
--opt-levelOptimization level: 0, 1, 2, 3, s, z. Translates to -C opt-level=.
-l, --libLink library (-l<lib>). May be repeated.
-L, --libdirLibrary search path (-L<dir>). May be repeated.
--externExternal crate (--extern name=path). May be repeated.
--cfgcfg flag (--cfg <spec>, e.g. feature="x"). May be repeated.
-a, --argsRuntime args passed to the compiled binary.
-t, --timePrint wall-clock time of compile + run.
-k, --keepPrint the compiled binary path so the user can inspect it.
--extra-rustflagRaw extra flag forwarded verbatim to rustc. Use sparingly.

Options for JavaScript and TypeScript​

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

OptionHelp text
-a, --argsRuntime args passed to the script (process.argv).
-t, --timePrint wall-clock run time.
-k, --keepPrint the written script path so the user can inspect it.
--extra-node-flagRaw extra flag forwarded verbatim to node. Use sparingly.

Examples​

C++ with the clang++ magic​

%%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:

sum = 15

C with the clang magic​

%%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:

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:

%%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:

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:

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, 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.

%%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 -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 *:

 sum of squares = 55

Rust with the rust magic​

%%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:

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]:

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

JavaScript with the node magic​

%%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:

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

TypeScript with the typescript magic​

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

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

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

The cell prints:

Green is 1

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

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

The cell prints:

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

Failures and time limits​

Code that does not compile​

%%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:

/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​

%%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:

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

A program that runs past the time limit​

%env EUGO_MAGIC_RUN_TIMEOUT_SECONDS=2
env: EUGO_MAGIC_RUN_TIMEOUT_SECONDS=2
%%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:

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:

%env EUGO_MAGIC_RUN_TIMEOUT_SECONDS=
env: EUGO_MAGIC_RUN_TIMEOUT_SECONDS=
  • Installing Python packages 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 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".