Metadata-Version: 2.4
Name: fortitudo
Version: 0.1.0
Summary: A browser-only compiler explorer for JupyterLab and Lumino.
Project-URL: Homepage, https://github.com/afshin/fortitudo
Project-URL: Bug Tracker, https://github.com/afshin/fortitudo/issues
Project-URL: Repository, https://github.com/afshin/fortitudo.git
Author-email: "A. T. Darian" <fortitudo@darian.at>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: jupyter,jupyterlab,jupyterlab-extension
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: jupyter-builder>=1.2.0; extra == 'dev'
Requires-Dist: jupyterlab>=4; extra == 'dev'
Description-Content-Type: text/markdown

# Fortitudo

Fortitudo is a browser-only C/C++ compiler explorer for JupyterLab, JupyterLite,
and a standalone Lumino application. All three hosts use the same workbench and
compiler worker. No kernel or remote compiler is needed.

Edit a function, choose a language, target, and optimization level, then select
**Compile** or press **Ctrl/Cmd+Enter**. Inspect assembly and compiler messages;
select a diagnostic to jump to its source location. Compilation runs in a
worker, so editing remains available. **Cancel** terminates that worker; the
next compile loads a fresh one.

The defaults are C++23, WebAssembly, and O2. C23 and O0–O3 are available. The
packaged LLVM runtime reports WebAssembly, x86-64, and AArch64 backends. Native
targets produce assembly with Clang built-in headers only; the packaged C/C++
system headers are for WebAssembly.

Source, options, and docked pane layout are saved by the host. Jupyter also
keeps a browser copy scoped to the current workspace, protecting recent edits
while its workspace writes are deferred. Reopening restores editing state
without compiling. Output is explicitly marked out of date when source or
options change. Invalid saved state opens a usable default session with
feedback.

## Running locally

The prebuilt extension requires JupyterLab 4.6 or later. Once the release is
published, install it with:

```sh
python -m pip install fortitudo
```

Restart JupyterLab and select **Open Fortitudo** in the launcher or command
palette. The wheel includes the compiler; installing it does not require Node or
a compiler build. The npm package also includes the runtime and exports the
shared workbench for applications that supply their own Lumino host.

See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete Pixi setup and build
sequence. The compiler is a separate heavyweight build; frontend builds require
its generated assets and verify their hashes.

For an already built checkout:

```sh
pixi run --as-is jupyter lab
pixi run --as-is jlpm serve
pixi run --as-is jlpm serve:standalone
```

In JupyterLab or JupyterLite, select **Open Fortitudo** in the launcher or
command palette. The Lite testbed is served on port 8080; the standalone preview
prints its local address. These commands run in separate terminals.

Built standalone and Lite directories can be served below a URL prefix. Keep
each site's `compiler` assets at their generated relative location. Serve `.js`
as JavaScript, `.wasm` as `application/wasm`, and `.data` as
`application/octet-stream`. Compilation works offline after initialization;
offline page reload is a separate feature.

## Architecture

- Pure model, request construction, and diagnostic parsing.
- One instance-owned store outside React.
- Lumino commands orchestrate semantic changes and compiler effects.
- Functional React views, with explicit store and CodeMirror bridges.
- A shared Lumino workbench owns layout, workers, and view lifecycles.
- Thin Jupyter and standalone adapters supply shell and persistence.

The shared package entry exports these contracts. Only `src/jupyter/` imports
JupyterLab packages; the plugin retains `fortitudo:plugin`.

## Runtime and limits

The runtime is reproduced from WasmBolt with LLVM 23.1.0 and Emscripten 4.0.9.
[runtime/README.md](runtime/README.md) records its origin, pins, licenses, and
build details. Generated `compiler/manifest.json` records asset sizes and
SHA-256 hashes. Browser test attachments record timings and Wasm memory
observations.

The current compiler is large and reserves 256 MiB of initial Wasm memory, with
memory growth enabled and a 32 MiB stack. Browser memory limits still apply.
Cancellation releases the worker; a later compile must initialize another.
Initialization and runtime failures offer a retry path. Ordinary compiler errors
retain diagnostics and raw output.

This implementation produces assembly. IR/AST views, MLIR tools, graphs,
execution, a terminal, sharing, arbitrary flags, automatic compilation, and
automatic timeouts are deferred. The optional upstream MLIR driver remains
packaged to preserve the runtime build, but is not downloaded eagerly.

## License

Fortitudo is BSD-3-Clause licensed. The compiler incorporates WasmBolt and other
separately licensed software. Required notices are included in
`runtime/licenses/` and copied into each distribution.
