### Example setup.py for Codon Extensions

Source: https://github.com/exaloop/codon/blob/develop/docs/integrations/python/extensions.md

This script configures setuptools to build Codon extensions. It finds the Codon installation, defines a custom build command to compile .codon files into Python extensions, and sets up the package structure.

```python
# setup.py
import os
import sys
import shutil
from pathlib import Path
from setuptools import setup, Extension
from setuptools.command.build_ext import build_ext

# Find Codon
codon_path = os.environ.get('CODON_DIR')
if not codon_path:
    c = shutil.which('codon')
    if c:
        codon_path = Path(c).parent / '..'
else:
    codon_path = Path(codon_path)
for path in [
    os.path.expanduser('~') + '/.codon',
    os.getcwd() + '/..',
]:
    path = Path(path)
    if not codon_path and path.exists():
        codon_path = path
        break

if (
    not codon_path
    or not (codon_path / 'include' / 'codon').exists()
    or not (codon_path / 'lib' / 'codon').exists()
):
    print(
        'Cannot find Codon.',
        'Please either install Codon (https://github.com/exaloop/codon)',
        'or set CODON_DIR if Codon is not in PATH.',
        file=sys.stderr,
    )
    sys.exit(1)
codon_path = codon_path.resolve()
print('Found Codon:', str(codon_path))

# Build with Codon
class CodonExtension(Extension):
    def __init__(self, name, source):
        self.source = source
        super().__init__(name, sources=[], language='c')

class BuildCodonExt(build_ext):
    def build_extensions(self):
        pass

    def run(self):
        inplace, self.inplace = self.inplace, False
        super().run()
        for ext in self.extensions:
            self.build_codon(ext)
        if inplace:
            self.copy_extensions_to_source()

    def build_codon(self, ext):
        extension_path = Path(self.get_ext_fullpath(ext.name))
        build_dir = Path(self.build_temp)
        os.makedirs(build_dir, exist_ok=True)
        os.makedirs(extension_path.parent.absolute(), exist_ok=True)

        codon_cmd = str(codon_path / 'bin' / 'codon')
        optimization = '-debug' if self.debug else '-release'
        self.spawn([codon_cmd, 'build', optimization, '--relocation-model=pic', '-pyext',
                    '-o', str(extension_path) + ".o", '-module', ext.name, ext.source])

        ext.runtime_library_dirs = [str(codon_path / 'lib' / 'codon')]
        self.compiler.link_shared_object(
            [str(extension_path) + '.o'],
            str(extension_path),
            libraries=['codonrt'],
            library_dirs=ext.runtime_library_dirs,
            runtime_library_dirs=ext.runtime_library_dirs,
            extra_preargs=['-Wl,-rpath,@loader_path'],
            debug=self.debug,
            build_temp=self.build_temp,
        )
        self.distribution.codon_lib = extension_path

setup(
    name='mymodule',
    version='0.1',
    packages=['mymodule'],
    ext_modules=[
        CodonExtension('mymodule', 'mymodule.codon'),
    ],
    cmdclass={'build_ext': BuildCodonExt}
)

```

--------------------------------

### Install Codon

Source: https://github.com/exaloop/codon/blob/develop/docs/labs/catalog/start.md

Run this shell command to install Codon. Ensure you have bash and curl installed.

```bash
/bin/bash -c "$(curl -fsSL https://exaloop.io/install.sh)"
```

--------------------------------

### Codon JIT Initialization and Execution Example

Source: https://github.com/exaloop/codon/blob/develop/docs/integrations/cpp/jit.md

A minimal C++ example demonstrating how to initialize the Codon JIT and execute a simple Codon code string.

```APIDOC
## Minimal Example

This example shows how to use the `codon::jit::JIT` class to compile and execute Codon code from C++.

### Code

```cpp
#include <iostream>

#include "codon/compiler/jit.h"

int main(int argc, char **argv) {
  std::string mode = "";
  std::string stdlib = "/path/to/.codon/lib/codon/stdlib"; // Adjust this path
  std::string code = "sum(i**2 for i in range(10))";

  codon::jit::JIT jit(argv[0], mode, stdlib);
  llvm::cantFail(jit.init());
  std::cout << llvm::cantFail(jit.execute(code)) << std::endl;
}
```

### `codon::jit::JIT` Constructor Arguments

- `argv[0]`: The first argument passed to the `main` function.
- `mode`: A string that can be empty or `"jupyter"`. Using `"jupyter"` enables support for the `_repr_mimebundle_` method.
- `stdlib`: The path to the Codon standard library. Defaults to `~/.codon/lib/codon/stdlib` for standard installations.

### Initialization

The `init()` method initializes the JIT. It uses LLVM's error handling, so `llvm::cantFail()` is used to handle potential errors.

### Execution

The `execute()` method compiles and runs the provided Codon code string, returning its captured output.

### Compilation

To compile this C++ program, use the following command, ensuring `CODON_DIR` is set to your Codon installation path:

```bash
export CODON_DIR=~/.codon  # Or your Codon installation directory
g++ -std=c++20 -I${CODON_DIR}/include \
               -L${CODON_DIR}/lib/codon \
               -Wl,-rpath,${CODON_DIR}/lib/codon \
               -lcodonc \
               test.cpp -o test_executable
```
```

--------------------------------

### Compile C++ with Codon JIT

Source: https://context7.com/exaloop/codon/llms.txt

Example of compiling a C++ file using Codon's JIT compiler. Ensure CODON_DIR is set to your Codon installation path.

```bash
export CODON_DIR=~/.codon
g++ -std=c++20 -I${CODON_DIR}/include \
    -L${CODON_DIR}/lib/codon \
    -Wl,-rpath,${CODON_DIR}/lib/codon \
    -lcodonc test.cpp
```

--------------------------------

### Install Codon using pip

Source: https://github.com/exaloop/codon/blob/develop/jit/README.md

Use this command to install Codon. If installed in a non-standard directory, set the CODON_DIR environment variable.

```bash
pip install .
```

--------------------------------

### Install codon-jit

Source: https://github.com/exaloop/codon/blob/develop/docs/integrations/python/codon-from-python.md

Install the `codon-jit` Python package using pip. This library enables Codon's JIT compilation.

```bash
pip install codon-jit
```

--------------------------------

### Example plugin.toml Configuration

Source: https://github.com/exaloop/codon/blob/develop/docs/developers/extend.md

This TOML file configures a Codon plugin, specifying its metadata and the C++ shared library to load.

```toml
[about]
name = "MyValidate"
description = "my validation plugin"
version = "0.0.1"
url = "https://example.com"
supported = ">=0.18.0"

[library]
cpp = "build/libmyvalidate"
```

--------------------------------

### Install Codon runtime and core libraries

Source: https://github.com/exaloop/codon/blob/develop/CMakeLists.txt

This section specifies the installation rules for various Codon components, including shared libraries, executables, headers, and standard library files, to their respective destinations.

```cmake
install(TARGETS codonrt codonc codon_jupyter DESTINATION lib/codon)
install(FILES ${CMAKE_BINARY_DIR}/libomp${CMAKE_SHARED_LIBRARY_SUFFIX} DESTINATION lib/codon)
install(FILES ${copied_libgfortran} DESTINATION lib/codon)
# only install libquadmath if it exists at build time
install(CODE "
  file(GLOB _quadmath "${copied_libquadmath}")
  if(EXISTS "${_quadmath}")
    file(INSTALL DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/codon" TYPE FILE FILES "${_quadmath}")
  endif()
")
install(FILES ${copied_libgcc} DESTINATION lib/codon)
install(TARGETS codon DESTINATION bin)
install(DIRECTORY ${CMAKE_BINARY_DIR}/include/codon DESTINATION include)
install(DIRECTORY ${LLVM_INCLUDE_DIRS}/llvm DESTINATION include)
install(DIRECTORY ${LLVM_INCLUDE_DIRS}/llvm-c DESTINATION include)
install(DIRECTORY ${CMAKE_SOURCE_DIR}/stdlib DESTINATION lib/codon)
install(DIRECTORY ${CMAKE_SOURCE_DIR}/jit/ DESTINATION python)
install(DIRECTORY DESTINATION lib/codon/plugins)
```

--------------------------------

### Python Code Example

Source: https://github.com/exaloop/codon/blob/develop/docs/developers/compilation.md

Example of Python code that will be parsed into an AST.

```python
x = 2 + 3
```

--------------------------------

### Python Generator Example

Source: https://github.com/exaloop/codon/blob/develop/docs/developers/compilation.md

A simple Python loop that demonstrates generator usage.

```python
for i in range(3):
    print(i)
```

--------------------------------

### Install Codon Jupyter Library

Source: https://github.com/exaloop/codon/blob/develop/jupyter/CMakeLists.txt

Installs the 'codon_jupyter' target to the root of the installation directory. This makes the compiled library available for use by other projects or the system.

```cmake
install(TARGETS codon_jupyter DESTINATION .)
```

--------------------------------

### Codon Jupyter Kernel Configuration with Plugins

Source: https://github.com/exaloop/codon/blob/develop/docs/integrations/jupyter.md

This `kernel.json` example shows how to specify optional plugins for the Codon kernel in Jupyter. Adjust the plugin path as needed.

```json
{
    "display_name": "Codon",
    "argv": [
        "/path/to/codon",
        "jupyter",
        "-plugin", "/path/to/plugin",
        "{connection_file}"
    ],
    "language": "python"
}
```

--------------------------------

### Python Program Structure Example

Source: https://github.com/exaloop/codon/blob/develop/docs/developers/compilation.md

A Python snippet demonstrating top-level code execution.

```python
a = 42
print(a * 2)
```

--------------------------------

### Run a Python Program with Codon

Source: https://github.com/exaloop/codon/blob/develop/docs/start/install.md

Compile and run a simple Python program using the `codon run` subcommand. This example demonstrates a basic 'Hello, World!' output.

```python
print('Hello, World!')
```

```bash
codon run hello.py
```

--------------------------------

### Minimal C++ Example for Codon JIT

Source: https://github.com/exaloop/codon/blob/develop/docs/integrations/cpp/jit.md

Demonstrates basic usage of the Codon JIT by compiling and executing a simple Codon code string. Ensure the Codon standard library path is correctly set.

```cpp
#include <iostream>

#include "codon/compiler/jit.h"

int main(int argc, char **argv) {
  std::string mode = "";
  std::string stdlib = "/path/to/.codon/lib/codon/stdlib";
  std::string code = "sum(i**2 for i in range(10))";

  codon::jit::JIT jit(argv[0], mode, stdlib);
  llvm::cantFail(jit.init());
  std::cout << llvm::cantFail(jit.execute(code)) << std::endl;
}
```

--------------------------------

### Calling a Compiled Function

Source: https://github.com/exaloop/codon/blob/develop/docs/integrations/cpp/jit.md

Example of casting a retrieved function pointer and calling it. Assumes `jit`, `code`, `f`, and `p` are defined as in previous examples.

```cpp
auto *f = llvm::cantFail(jit.compile(code));
auto *p = llvm::cantFail(jit.address(f));
reinterpret_cast<void (*)()>(p)();  // prints 285
```

--------------------------------

### Set Installation RPATH

Source: https://github.com/exaloop/codon/blob/develop/CMakeLists.txt

Configures the installation RPATH for shared libraries, adapting the path based on the operating system (Apple vs. others).

```cmake
set(CMAKE_BUILD_WITH_INSTALL_RPATH ON)
if(APPLE)
  set(CMAKE_INSTALL_RPATH "@loader_path;@loader_path/../lib/codon")
else()
  set(CMAKE_INSTALL_RPATH "$ORIGIN:$ORIGIN/../lib/codon")
endif()
```

--------------------------------

### Building Python Extensions with Codon

Source: https://context7.com/exaloop/codon/llms.txt

Demonstrates how to compile Codon code into Python extension modules. Includes examples of function overloading, Python extension types using dataclasses, and NumPy array processing for PyTorch.

```python
# extension.codon
import numpy as np
import numpy.pybridge

def foo(a: int, b: float, c: str):
    return a * b + float(c)

# Function overloading
def bar(x: int):
    return x + 2

@overload
def bar(x: str):
    return x * 2

# Python extension types
@dataclass(python=True)
class Vec:
    x: float
    y: float

    def __init__(self, x: float = 0.0, y: float = 0.0):
        self.x = x
        self.y = y

    def __add__(self, other: Vec):
        return Vec(self.x + other.x, self.y + other.y)

    def __repr__(self):
        return f'Vec({self.x}, {self.y})'

# NumPy array processing for PyTorch
def initialize(arr: np.ndarray[np.float32, 3]):
    for i in range(128):
        for j in range(128):
            for k in range(128):
                arr[i, j, k] = i + j + k
```

```bash
# Build Python extension
codon build -pyext -release --relocation-model=pic -module mymodule extension.codon

# Use from Python
python3 -c "from mymodule import Vec; print(Vec(3.0, 4.0) + Vec(1, 2))"
# Vec(4.0, 6.0)
```

--------------------------------

### Codon Example for Bidirectionality

Source: https://github.com/exaloop/codon/blob/develop/docs/developers/ir.md

Illustrates a simple Codon function and its usage with different types.

```python
def foo(x):
    return x*3 + x

def validate(x, y):
    assert y == x*4

a = foo(10)
b = foo(1.5)
c = foo('a')
```

--------------------------------

### JIT REPL Mode

Source: https://github.com/exaloop/codon/blob/develop/docs/start/usage.md

Running `codon jit` without arguments starts an interactive REPL. Inputs can be separated by `%%`.

```bash
# %%
```

--------------------------------

### Using Matplotlib with Codon

Source: https://github.com/exaloop/codon/blob/develop/README.md

Example of importing and using a Python library (matplotlib.pyplot) from Codon. Ensure CODON_PYTHON environment variable is set.

```python
from python import matplotlib.pyplot as plt
data = [x**2 for x in range(10)]
plt.plot(data)
plt.show()
```

--------------------------------

### Initialize PyTorch Tensor using Codon JIT

Source: https://github.com/exaloop/codon/blob/develop/docs/libraries/numpy.md

Example of initializing a large PyTorch tensor efficiently using Codon's JIT compilation. This demonstrates a significant speedup compared to standard Python execution.

```python
import numpy as np
import time
import codon
import torch

@codon.jit
def initialize(arr):
    for i in range(128):
        for j in range(128):
            for k in range(128):
                arr[i, j, k] = i + j + k

# first call JIT-compiles; subsequent calls use cached JIT'd code
tensor = torch.empty(128, 128, 128)
initialize(tensor.numpy())

tensor = torch.empty(128, 128, 128)
t0 = time.time()
initialize(tensor.numpy())
t1 = time.time()

print(tensor)
print(t1 - t0, 'seconds')
```

--------------------------------

### Install nlohmann_json Target

Source: https://github.com/exaloop/codon/blob/develop/jupyter/CMakeLists.txt

Installs the 'nlohmann_json' target for the 'xeus-targets' export if the 'xeus' package was successfully added. This makes the JSON library available for linking.

```cmake
if (xeus_ADDED)
    install(TARGETS nlohmann_json EXPORT xeus-targets)
endif()
```

--------------------------------

### Fetch and configure googletest for testing

Source: https://github.com/exaloop/codon/blob/develop/CMakeLists.txt

This section uses FetchContent to download and make googletest available for the project's testing framework. It includes specific settings for Windows compatibility and disables gtest installation.

```cmake
include(FetchContent)
FetchContent_Declare(
  googletest
  URL https://github.com/google/googletest/archive/03597a01ee50ed33e9dfd640b249b4be3799d395.zip
)
# For Windows: Prevent overriding the parent project's compiler/linker settings
set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
option(INSTALL_GTEST "Enable installation of googletest." OFF)
FetchContent_MakeAvailable(googletest)
enable_testing()
```

--------------------------------

### Compiling Codon JIT with g++

Source: https://github.com/exaloop/codon/blob/develop/docs/integrations/cpp/jit.md

Provides the command to compile a C++ file that uses the Codon JIT library. Ensure CODON_DIR is set to your Codon installation path.

```bash
export CODON_DIR=~/.codon  # or wherever Codon is installed
g++ -std=c++20 -I${CODON_DIR}/include \
               -L${CODON_DIR}/lib/codon \
               -Wl,-rpath,${CODON_DIR}/lib/codon \
               -lcodonc \
               test.cpp
```

--------------------------------

### Python Dynamic Inheritance Example

Source: https://github.com/exaloop/codon/blob/develop/docs/language/classes.md

Demonstrates overriding methods like `area` and `describe` in subclasses of `Shape`. This example showcases polymorphism with a list of different shape objects.

```python
class Shape:

    def area(self):
        return 0.0

    def describe(self):
        return "This is a shape."

class Circle(Shape):
    radius: float

    def __init__(self, radius):
        self.radius = radius

    def area(self):
        return 3.1416 * self.radius**2

    def describe(self):
        return f"A circle with radius {self.radius}"

class Rectangle(Shape):
    width: float
    height: float

    def __init__(self, width, height):
        self.width = width
        self.height = height

    def area(self):
        return self.width * self.height

    def describe(self):
        return f"A rectangle with width {self.width} and height {self.height}"

class Square(Rectangle):

    def __init__(self, width):
        super().__init__(width, width)

    def describe(self):
        return super().describe().replace('rectangle', 'square')


shapes: list[Shape] = []
shapes.append(Circle(5))
shapes.append(Rectangle(4, 6))
shapes.append(Square(3))

for shape in shapes:
    print(shape.describe(), f'(area={shape.area()})')

```

--------------------------------

### Simple GPU Kernel in Codon

Source: https://context7.com/exaloop/codon/llms.txt

A basic example of a CUDA kernel using the `@gpu.kernel` decorator for element-wise array addition. It demonstrates how to define a kernel function and launch it on the GPU with specified grid and block dimensions.

```Python
import gpu

@gpu.kernel
def add_arrays(a, b, c):
    i = gpu.thread.x
    c[i] = a[i] + b[i]

a = [i for i in range(16)]
b = [2*i for i in range(16)]
c = [0 for _ in range(16)]

add_arrays(a, b, c, grid=1, block=16)
print(c)  # [0, 3, 6, ..., 45]
```

--------------------------------

### NumPy Fusion Optimization Verbose Output

Source: https://github.com/exaloop/codon/blob/develop/docs/libraries/numpy.md

Example output from Codon's `-npfuse-verbose` flag, showing how the compiler analyzes and optimizes expressions for fusion.

```text
Optimizing expression at pi.py:10:7
lt <array[bool, 1]> [cost=6] 
  add <array[f64, 1]> [cost=5] 
    pow <array[f64, 1]> [cost=2] 
      sub <array[f64, 1]> [cost=1] 
        a0 <array[f64, 1]> 
        a1 <i64> 
      a2 <i64> 
    pow <array[f64, 1]> [cost=2] 
      sub <array[f64, 1]> [cost=1] 
        a3 <array[f64, 1]> 
        a4 <i64> 
      a5 <i64> 
  a6 <i64> 

-> static fuse:
lt <array[bool, 1]> [cost=6] 
  add <array[f64, 1]> [cost=5] 
    pow <array[f64, 1]> [cost=2] 
      sub <array[f64, 1]> [cost=1] 
        a0 <array[f64, 1]> 
        a1 <i64> 
      a2 <i64> 
    pow <array[f64, 1]> [cost=2] 
      sub <array[f64, 1]> [cost=1] 
        a3 <array[f64, 1]> 
        a4 <i64> 
      a5 <i64> 
  a6 <i64>
```

--------------------------------

### Optimized LLVM IR for Generator

Source: https://github.com/exaloop/codon/blob/develop/docs/developers/compilation.md

The highly optimized LLVM IR for the generator example after LLVM optimizations, showing the elided coroutine overhead.

```llvm
  call void @print(i64 0)
  call void @print(i64 1)
  call void @print(i64 2)
```

--------------------------------

### Configure Codon Path and Installation Prefix

Source: https://github.com/exaloop/codon/blob/develop/jupyter/CMakeLists.txt

Sets the CODON_PATH variable, defaulting to '$ENV{HOME}/.codon' if not already defined. It also configures the CMAKE_INSTALL_PREFIX to point to the Codon library directory within the determined CODON_PATH.

```cmake
if(NOT CODON_PATH)
    set(CODON_PATH "$ENV{HOME}/.codon")
endif()
message(STATUS "Found Codon in ${CODON_PATH}")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${CODON_PATH}/lib/codon/" CACHE PATH "Use the existing Codon installation" FORCE)
endif(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
```

--------------------------------

### Run Optimized Python Program with Codon

Source: https://github.com/exaloop/codon/blob/develop/docs/start/install.md

Enable optimizations when running a Python program with Codon using the `-release` flag. This example calculates the 40th Fibonacci number and measures execution time.

```python
from time import time

def fib(n):
    return n if n < 2 else fib(n - 1) + fib(n - 2)

t0 = time()
ans = fib(40)
t1 = time()
print(f'Computed fib(40) = {ans} in {t1 - t0} seconds.')
```

```bash
codon run -release fib.py
```

--------------------------------

### Call Codon-Initialized Function from Python

Source: https://github.com/exaloop/codon/blob/develop/docs/libraries/numpy.md

Import and call a Codon-compiled Python extension function. This example initializes a PyTorch tensor's underlying NumPy array.

```python
from codon_initialize import initialize
import torch

tensor = torch.empty(128, 128, 128)
initialize(tensor.numpy())
print(tensor)
```

--------------------------------

### C++ Plugin Implementation with load() function

Source: https://github.com/exaloop/codon/blob/develop/docs/developers/extend.md

Implements a Codon plugin by extending codon::DSL and providing a load() function. This example registers a custom IR pass.

```cpp
class MyValidate : public codon::DSL {
public:
  void addIRPasses(transform::PassManager *pm, bool debug) override {
    std::string insertBefore = debug ? "" : "core-folding-pass-group";
    pm->registerPass(std::make_unique<ValidateFoo>(), insertBefore);
  }
};

extern "C" std::unique_ptr<codon::DSL> load() {
  return std::make_unique<MyValidate>();
}
```

--------------------------------

### Build LLVM Fork for Codon

Source: https://github.com/exaloop/codon/blob/develop/docs/developers/build.md

Clone and build the specific LLVM fork required by Codon. Ensure to set the correct build type and enable necessary projects like OpenMP. The installation prefix should be set to avoid system LLVM conflicts.

```bash
git clone --depth 1 -b codon https://github.com/exaloop/llvm-project
cmake -S llvm-project/llvm -B llvm-project/build \
    -DCMAKE_BUILD_TYPE=Release \
    -DLLVM_INCLUDE_TESTS=OFF \
    -DLLVM_ENABLE_RTTI=ON \
    -DLLVM_ENABLE_ZLIB=OFF \
    -DLLVM_ENABLE_ZSTD=OFF \
    -DLLVM_ENABLE_PROJECTS="openmp" \
    -DLLVM_TARGETS_TO_BUILD=all
cmake --build llvm-project/build
cmake --install llvm-project/build --prefix=llvm-project/install
```

--------------------------------

### Build Codon Jupyter Plugin (Linux)

Source: https://github.com/exaloop/codon/blob/develop/docs/developers/build.md

Configure and build the Jupyter plugin for Codon on Linux systems. This requires specifying compiler paths, LLVM directory, Codon installation path, and OpenSSL library locations. Ensure OPENSSL_CRYPTO_LIBRARY path is correct for your system.

```bash
# Linux version:
cmake -S jupyter -B jupyter/build \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_C_COMPILER=clang \
    -DCMAKE_CXX_COMPILER=clang++ \
    -DLLVM_DIR=$(llvm-config --cmakedir) \
    -DCODON_PATH=install \
    -DOPENSSL_ROOT_DIR=$(openssl version -d | cut -d' ' -f2 | tr -d '"') \
    -DOPENSSL_CRYPTO_LIBRARY=/usr/lib64/libssl.so \
    -DXEUS_USE_DYNAMIC_UUID=ON
# n.b. OPENSSL_CRYPTO_LIBRARY might differ on your system.

# On macOS, do this instead:
OPENSSL_ROOT_DIR=/usr/local/opt/openssl cmake -S jupyter -B jupyter/build \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_C_COMPILER=clang \
    -DCMAKE_CXX_COMPILER=clang++ \
    -DLLVM_DIR=$(llvm-config --cmakedir) \
    -DCODON_PATH=install

# Then:
cmake --build jupyter/build
cmake --install jupyter/build
```

--------------------------------

### Call C Function with Pointer Argument

Source: https://github.com/exaloop/codon/blob/develop/docs/language/lowlevel.md

Interface with C functions that require pointer arguments by using `__ptr__` to get a pointer to a Codon variable. This example shows calling `frexp` from the C standard library.

```python
from C import frexp(float, Ptr[i32]) -> float

x = 16.4
exponent = i32()
mantissa = frexp(x, __ptr__(exponent))  # equivalent to 'frexp(x, &exponent)' in C

print(mantissa, exponent)  # 0.5125 5
```

--------------------------------

### Build Codon Extensions with Setuptools

Source: https://github.com/exaloop/codon/blob/develop/docs/integrations/python/extensions.md

Execute this command in your project directory to build the Codon extensions defined in your setup.py. The `--inplace` flag ensures the compiled extension is placed directly in the current directory for immediate use.

```bash
python3 setup.py build_ext --inplace
```

--------------------------------

### Execute fix_loader_paths.sh on macOS during installation

Source: https://github.com/exaloop/codon/blob/develop/CMakeLists.txt

This install rule conditionally executes a bash script to fix loader paths on macOS systems after installation. It checks the return code and reports errors if the script fails.

```cmake
install(CODE [[ 
  if(APPLE)
    # Compute the real install root (supports DESTDIR)
    set(_root "$ENV{DESTDIR}${CMAKE_INSTALL_PREFIX}")
    message(STATUS "fix_loader_paths.sh on: ${_root}")
    execute_process(
      COMMAND /bin/bash "${CMAKE_SOURCE_DIR}/scripts/fix_loader_paths.sh" "${_root}"
      RESULT_VARIABLE rc
    )
    if(NOT rc EQUAL 0)
      message(FATAL_ERROR "fix_loader_paths.sh failed with code ${rc}")
    endif()
  endif()
]])
```

--------------------------------

### Static Inheritance with Classes

Source: https://github.com/exaloop/codon/blob/develop/docs/language/classes.md

Illustrates static inheritance using `Static[Foo]` for early binding. This approach bypasses dynamic dispatch costs for performance benefits.

```python
class Foo:
    x: int

    def __init__(self, x: int):
        self.x = x

    def hello(self):
        print('Foo')

class Bar(Static[Foo]):

    def hello(self):
        print('Bar')

foo = Foo(1)
bar = Bar(2)

print(foo.x, bar.x)  # 1 2
foo.hello()          # Foo
bar.hello()          # Bar

```

--------------------------------

### JIT Compilation with @codon.jit

Source: https://context7.com/exaloop/codon/llms.txt

The `@codon.jit` decorator compiles individual Python functions to native code at runtime. Install via `pip install codon-jit`. It can be used with `debug=True` for debugging output. Python variables can be passed to JIT'd functions using `pyvars`. Custom classes can be converted for Codon using `@codon.convert`.

```python
import codon
from time import time

def is_prime_python(n):
    if n <= 1:
        return False
    for i in range(2, n):
        if n % i == 0:
            return False
    return True

@codon.jit
def is_prime_codon(n):
    if n <= 1:
        return False
    for i in range(2, n):
        if n % i == 0:
            return False
    return True

# Compare performance
t0 = time()
ans = sum(1 for i in range(100000, 200000) if is_prime_python(i))
t1 = time()
print(f'[python] {ans} | took {t1 - t0} seconds')
# [python] 8392 | took 39.66 seconds

t0 = time()
ans = sum(1 for i in range(100000, 200000) if is_prime_codon(i))
t1 = time()
print(f'[codon]  {ans} | took {t1 - t0} seconds')
# [codon]  8392 | took 0.99 seconds
```

```python
# Using @codon.jit with debug output
@codon.jit(debug=True)
def sum_of_squares(v):
    return sum(i**2 for i in v)
```

```python
# Pass Python globals to JIT'd functions
def callback(n):
    print(f'n is {n}')

@codon.jit(pyvars=['callback'])
def process(n):
    callback(n)  # calls the Python function
    return n ** 2
```

```python
# Convert custom classes for Codon
@codon.convert
class Point:
    __slots__ = 'x', 'y'

    def __init__(self, x, y):
        self.x = x
        self.y = y

    @codon.jit
    def distance(self):
        return (self.x**2 + self.y**2) ** 0.5
```

--------------------------------

### Create datetime64 and timedelta64 arrays

Source: https://github.com/exaloop/codon/blob/develop/docs/libraries/numpy.md

Demonstrates creating NumPy arrays with specific datetime64 and timedelta64 data types and units.

```python
dt = np.array(['2020-01-02', '2021-09-15', '2022-07-01'],
              dtype=np.datetime64['D', 1])

td = np.array([100, 200, 300], dtype=np.timedelta64['m', 15])
```

--------------------------------

### Recursive Fibonacci Function in Python

Source: https://github.com/exaloop/codon/blob/develop/docs/developers/ir.md

A simplified recursive implementation of the Fibonacci sequence. This serves as an example for CIR generation.

```python
def fib(n):
    if n < 2:
        return 1
    else:
        return fib(n - 1) + fib(n - 2)
```

--------------------------------

### Array Programming with Codon

Source: https://context7.com/exaloop/codon/llms.txt

Demonstrates array creation, loading, linear algebra, random number generation, expression fusion, parallel and GPU processing, and datetime support. Also shows passing array data to C.

```python
arr = np.array([[1.1, 2.2], [3.3, 4.4]])
print(arr.__class__.__name__)  # ndarray[float,2]
```

```python
arr = np.load('arr.npy', dtype=float, ndim=3)
```

```python
eigenvalues, eigenvectors = LA.eig(np.diag((1, 2, 3)))
print(eigenvalues)  # 1.+0.j 2.+0.j 3.+0.j
```

```python
rng = rnd.default_rng(seed=0)
x = rng.random(500_000_000)
y = rng.random(500_000_000)
```

```python
pi = ((x-1)**2 + (y-1)**2 < 1).sum() * (4 / len(x))
```

```python
N = 100000000
n = 10
x = rng.normal(size=(N, n))
y = np.empty(n)

@par(num_threads=n)
for i in range(n):
    y[i] = x[:, i].sum()
```

```python
pixels = np.empty((N, N), int)

@gpu.kernel
def mandelbrot(pixels):
    i = (gpu.block.x * gpu.block.dim.x) + gpu.thread.x
    j = (gpu.block.y * gpu.block.dim.y) + gpu.thread.y
    # ... computation
    pixels[i, j] = 255 * iteration/MAX

mandelbrot(pixels, grid=(N//32, N//32), block=(32, 32))
```

```python
dt = np.array(['2020-01-02', '2021-09-15'],
              dtype=np.datetime64['D', 1])
td = np.array([100, 200], dtype=np.timedelta64['m', 15])
```

```python
from C import foo(p: Ptr[float], n: int)
arr = np.array([1.0, 2.0, 3.0])
foo(arr.data, arr.size)
```

--------------------------------

### Run Python Program from Standard Input

Source: https://github.com/exaloop/codon/blob/develop/docs/start/usage.md

Pipe Python code to `codon run -` to compile and execute from standard input. Use `-release` for optimized execution.

```bash
echo 'print("hello")' | codon run -release -
```

--------------------------------

### Get Pointer to a Variable

Source: https://github.com/exaloop/codon/blob/develop/docs/language/lowlevel.md

Obtain a pointer to an existing variable using the `__ptr__` intrinsic function. This is analogous to the address-of operator (`&`) in C.

```python
x = 42
p = __ptr__(x)  # 'p' is a 'Ptr[int]'; equivalent to '&x' in C
p[0] = 99
print(x)  # 99
```

--------------------------------

### Import C Standard Library Function

Source: https://github.com/exaloop/codon/blob/develop/docs/integrations/cpp/cpp-from-codon.md

Import the C standard library 'sqrt' function, specifying its argument and return types. Ensure the function signature matches C's ABI.

```python
# import the C standard library 'sqrt' function
from C import sqrt(float) -> float
print(sqrt(2.0))  # 1.41421
```

--------------------------------

### Enable transparent hugepages on Linux

Source: https://github.com/exaloop/codon/blob/develop/docs/libraries/numpy.md

Command to enable transparent hugepages on a Linux system. Requires root privileges.

```bash
echo "always" | sudo tee /sys/kernel/mm/transparent_hugepage/enabled
```

--------------------------------

### Import and Use Matplotlib in Codon

Source: https://github.com/exaloop/codon/blob/develop/docs/integrations/python/python-from-codon.md

Import third-party Python libraries such as Matplotlib in Codon to create plots. Ensure Matplotlib is installed in your Python environment.

```python
from python import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5]
y = [2, 5, 3, 6, 4]

fig, ax = plt.subplots()
ax.plot(x, y)
plt.show()
```

--------------------------------

### Getting Compiled Function Address

Source: https://github.com/exaloop/codon/blob/develop/docs/integrations/cpp/jit.md

Retrieves a pointer to a compiled Codon IR function. The pointer can be cast to the appropriate function pointer type and invoked.

```cpp
llvm::Expected<void *> address(const ir::Func *input,
                               llvm::orc::ResourceTrackerSP rt = nullptr);
```

--------------------------------

### Download and Include CPM.cmake

Source: https://github.com/exaloop/codon/blob/develop/jupyter/CMakeLists.txt

Downloads the CPM.cmake build system helper if it doesn't exist and then includes it. This facilitates managing external C++ dependencies using CMake's `CPMAddPackage` command.

```cmake
set(CPM_DOWNLOAD_VERSION 0.32.3)
set(CPM_DOWNLOAD_LOCATION "${CMAKE_BINARY_DIR}/cmake/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
if(NOT (EXISTS ${CPM_DOWNLOAD_LOCATION}))
    message(STATUS "Downloading CPM.cmake...")
    file(DOWNLOAD https://github.com/TheLartians/CPM.cmake/releases/download/v${CPM_DOWNLOAD_VERSION}/CPM.cmake ${CPM_DOWNLOAD_LOCATION})
endif()
include(${CPM_DOWNLOAD_DOWNLOAD_LOCATION})
```

--------------------------------

### Create Tuples with Static Loops in Codon

Source: https://context7.com/exaloop/codon/llms.txt

Example of creating tuples using static loops and generator expressions in Codon. The tuple `t` is generated at compile time.

```python
# Create tuples with static loops
t = tuple(i*i for i in static.range(5))
print(t)  # (0, 1, 4, 9, 16)
```

--------------------------------

### Configure Project-Specific Files

Source: https://github.com/exaloop/codon/blob/develop/CMakeLists.txt

Uses configure_file to process input files and generate configuration headers and Python version files.

```cmake
set(CODON_JIT_PYTHON_VERSION "0.4.6")
configure_file("${PROJECT_SOURCE_DIR}/cmake/config.h.in"
               "${PROJECT_SOURCE_DIR}/codon/config/config.h")
configure_file("${PROJECT_SOURCE_DIR}/cmake/config.py.in"
               "${PROJECT_SOURCE_DIR}/jit/codon/version.py")
```

--------------------------------

### JIT API Methods

Source: https://github.com/exaloop/codon/blob/develop/docs/integrations/cpp/jit.md

Detailed descriptions of the methods available in the `codon::jit::JIT` class.

```APIDOC
## JIT API

### `init`

```cpp
llvm::Error init(bool forgetful = false);
```

Initializes the JIT compiler. If `forgetful` is set to `true`, the JIT will not retain global variables or functions from previous inputs, effectively providing a fresh JIT state for each input without repeated initialization overhead.

### `compile` (code string)

```cpp
llvm::Expected<ir::Func *> compile(const std::string &code, const std::string &file = "", int line = 0);
```

Compiles the given `code` string into a Codon Intermediate Representation (IR) function. Optional `file` and `line` arguments can provide source location information. This method does not invoke the LLVM backend.

### `compile` (IR function)

```cpp
llvm::Error compile(const ir::Func *input, llvm::orc::ResourceTrackerSP rt = nullptr);
```

Compiles a provided Codon IR function (`input`) within the JIT. An optional `llvm::orc::ResourceTracker` can be supplied to manage the JIT-compiled code. A resource tracker can be obtained using `jit.getEngine()->getMainJITDylib().createResourceTracker()`.

### `address`

```cpp
llvm::Expected<void *> address(const ir::Func *input, llvm::orc::ResourceTrackerSP rt = nullptr);
```

Returns a pointer to the compiled function corresponding to the given Codon IR function (`input`). Similar to the `compile` method for IR functions, an optional `llvm::orc::ResourceTracker` can be provided. The returned pointer can be cast to the appropriate function pointer type and invoked.

Example:

```cpp
auto *f = llvm::cantFail(jit.compile(code));
auto *p = llvm::cantFail(jit.address(f));
reinterpret_cast<void (*)()>(p)(); // Executes the compiled function
```

### `execute`

```cpp
llvm::Expected<std::string> execute(const std::string &code, const std::string &file = "", int line = 0, bool debug = false, llvm::orc::ResourceTrackerSP rt = nullptr);
```

Executes the full compilation pipeline for the given `code` string and returns its captured output. Optional arguments allow specifying source file and line information, enabling debug mode, and managing resources with a `ResourceTracker`.
```

--------------------------------

### Run Program with Arguments from Standard Input

Source: https://github.com/exaloop/codon/blob/develop/docs/start/usage.md

Execute Python code from standard input, passing arguments to the program. The first argument in `sys.argv` will be '-' if reading from stdin.

```bash
echo 'import sys; print(sys.argv)' | codon run -release - arg1 arg2 arg3
```

--------------------------------

### Compile-Time Definitions

Source: https://github.com/exaloop/codon/blob/develop/docs/start/usage.md

Use the `-D` flag to pass literal variables as compile-time constants for metaprogramming. For example, `-DN=16` sets a compile-time constant `N` to 16.

```python
n = Int[N](42)
print(n * n)
```

--------------------------------

### Get or Realize Method in CIR

Source: https://github.com/exaloop/codon/blob/develop/docs/developers/ir.md

Retrieves an existing method or generates a new one if it doesn't exist. This is used when dealing with methods associated with specific types.

```cpp
/// Gets or realizes a method.
/// @param parent the parent class
/// @param methodName the method name
/// @param rType the return type
/// @param args the argument types
/// @param generics the generics
/// @return the method or nullptr
Func *getOrRealizeMethod(types::Type *parent, const std::string &methodName,
                           std::vector<types::Type *> args,
                           std::vector<types::Generic> generics = {});
```

--------------------------------

### Set Minimum CMake Version and Project

Source: https://github.com/exaloop/codon/blob/develop/jupyter/CMakeLists.txt

Specifies the minimum required CMake version and defines project metadata including version, homepage, and description.

```cmake
cmake_minimum_required(VERSION 3.14)
project(
  CodonJupyter
  VERSION "0.1"
  HOMEPAGE_URL "https://github.com/exaloop/codon"
  DESCRIPTION "Jupyter support for Codon")
```

--------------------------------

### Get or Realize Function in CIR

Source: https://github.com/exaloop/codon/blob/develop/docs/developers/ir.md

Retrieves an existing function or generates a new one if it doesn't exist. Useful for dynamically creating or accessing functions during IR transformations.

```cpp
/// Gets or realizes a function.
/// @param funcName the function name
/// @param args the argument types
/// @param generics the generics
/// @param module the module of the function
/// @return the function or nullptr
Func *getOrRealizeFunc(const std::string &funcName, std::vector<types::Type *> args,
                         std::vector<types::Generic> generics = {},
                         const std::string &module = "");
```

--------------------------------

### JIT Compilation from Standard Input

Source: https://github.com/exaloop/codon/blob/develop/docs/start/usage.md

The `codon jit -` command reads from standard input for JIT compilation. This is useful for quick testing and debugging.

```bash
echo 'print("hello world")' | codon jit -
```

--------------------------------

### Define Tuple Classes in Codon

Source: https://context7.com/exaloop/codon/llms.txt

Example of defining immutable, stack-allocated tuple classes using the `@tuple` decorator in Codon. Supports multiple `__new__` methods for different initializations.

```python
# Tuple classes (immutable, stack-allocated)
@tuple
class Vector:
    x: int
    y: int

    def __new__():
        return Vector(0, 0)

    def __new__(x: int):
        return Vector(x, 0)
```

--------------------------------

### Run Codon Programs

Source: https://github.com/exaloop/codon/blob/develop/README.md

Commands for running and building Codon programs, including options for release mode and LLVM IR generation.

```bash
codon run file.py
```

```bash
codon run -release file.py
```

```bash
codon build -release file.py
```

```bash
codon build -release -llvm file.py
```

--------------------------------

### Get or Realize Type in CIR

Source: https://github.com/exaloop/codon/blob/develop/docs/developers/ir.md

Retrieves an existing type or generates a new one if it doesn't exist. This is essential for working with custom or dynamically generated types within the IR.

```cpp
/// Gets or realizes a type.
/// @param typeName mangled type name
/// @param generics the generics
/// @return the function or nullptr
types::Type *getOrRealizeType(const std::string &typeName,
                                std::vector<types::Generic> generics = {});
```

--------------------------------

### Inline LLVM IR Addition in Codon

Source: https://context7.com/exaloop/codon/llms.txt

Example of using inline LLVM IR in Codon for low-level operations. The `llvm_add` function performs addition using LLVM IR instructions.

```python
@llvm
def llvm_add(a: int, b: int) -> int:
    %res = add i64 %a, %b
    ret i64 %res

print(llvm_add(3, 4))  # 7
```

--------------------------------

### Find Required Packages

Source: https://github.com/exaloop/codon/blob/develop/CMakeLists.txt

Locates and includes necessary packages such as Threads and LLVM, printing their versions and paths.

```cmake
set(APPLE_ARM OFF)
if (APPLE AND CMAKE_HOST_SYSTEM_PROCESSOR STREQUAL "arm64")
  set(APPLE_ARM ON)
endif()

set(THREADS_PREFER_PTHREAD_FLAG ON)
find_package(Threads REQUIRED)
find_package(LLVM REQUIRED)

message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")
include(${CMAKE_SOURCE_DIR}/cmake/deps.cmake)
include(${CMAKE_SOURCE_DIR}/cmake/CMakeRC.cmake)
```

--------------------------------

### Importing Native and Python sys Modules

Source: https://github.com/exaloop/codon/blob/develop/docs/libraries/stdlib.md

Demonstrates how to import Codon's native 'sys' module and Python's 'sys' module when they might conflict. This is useful when needing to access specific Python functionalities not yet natively implemented in Codon.

```python
import sys              # uses Codon's native 'sys' module
from python import sys  # uses Python's 'sys' module
```

--------------------------------

### Implement Inheritance and Dynamic Dispatch in Codon

Source: https://context7.com/exaloop/codon/llms.txt

Example of inheritance and dynamic dispatch in Codon. A `Circle` class inherits from `Shape`, and the correct `area` method is called based on the object type.

```python
# Inheritance with dynamic dispatch
class Shape:
    def area(self):
        return 0.0

class Circle(Shape):
    radius: float

    def __init__(self, radius):
        self.radius = radius

    def area(self):
        return 3.1416 * self.radius**2

shapes: list[Shape] = [Circle(5)]
for shape in shapes:
    print(shape.area())
```

--------------------------------

### Compile C Application with Codon Library

Source: https://github.com/exaloop/codon/blob/develop/docs/integrations/cpp/codon-from-cpp.md

Compile the C/C++ application, linking it against the generated Codon shared library. Use `-L` to specify the library path and `-l` to specify the library name.

```bash
gcc -o foo -L. -lfoo foo.c  # or g++ if using C++
```

--------------------------------

### Parallelize NumPy Summation with Codon

Source: https://github.com/exaloop/codon/blob/develop/docs/libraries/numpy.md

Demonstrates parallel processing of NumPy array sums using Codon's `@par` decorator. This example utilizes multiple threads for faster computation.

```python
import numpy as np
import numpy.random as rnd
import time

N = 100000000
n = 10

rng = rnd.default_rng(seed=0)
x = rng.normal(size=(N,n))
y = np.empty(n)

t0 = time.time()

@par(num_threads=n)
for i in range(n):
    y[i] = x[:,i].sum()

t1 = time.time()

print(y)
print(t1 - t0, 'seconds')
```

--------------------------------

### Basic Codon JIT Usage

Source: https://github.com/exaloop/codon/blob/develop/jit/README.md

Import the codon library and use the @codon.jit decorator to compile Python functions for faster execution.

```python
import codon

@codon.jit
def ...
```

--------------------------------

### Use Codon-Generated Python Extension Type

Source: https://github.com/exaloop/codon/blob/develop/docs/integrations/python/extensions.md

Instantiate and use the generated Python extension type from Python code. This example demonstrates creating `Vec` objects and performing addition operations.

```python
from vec import Vec

a = Vec(x=3.0, y=4.0)  # Vec(3.0, 4.0)
b = a + Vec(1, 2)      # Vec(4.0, 6.0)
c = b + 10.0           # Vec(14.0, 16.0)
```