mirror of https://github.com/exaloop/codon.git
140 lines
7.3 KiB
Markdown
140 lines
7.3 KiB
Markdown
# Technical
|
|
|
|
## What is Codon?
|
|
|
|
Codon is a high-performance Python compiler that compiles Python code to native machine code
|
|
without any runtime overhead. Typical speedups over Python are on the order of 10-100x or more,
|
|
on a single thread. Codon's performance is typically on par with that of C/C++. Unlike Python,
|
|
Codon supports native multithreading, which can lead to speedups many times higher still.
|
|
Codon is extensible via a plugin infrastructure, which lets you incorporate new libraries,
|
|
compiler optimizations and even keywords.
|
|
|
|
## What isn't Codon?
|
|
|
|
While Codon supports nearly all of Python's syntax, it is not a drop-in replacement, and large
|
|
codebases might require modifications to be run through the Codon compiler. For example, some
|
|
of Python's modules are not yet implemented within Codon, and a few of Python's dynamic features
|
|
are disallowed. The Codon compiler produces detailed error messages to help identify and resolve
|
|
any incompatibilities. Codon supports seamless [Python interoperability](../interop/python.md) to
|
|
handle cases where specific Python libraries or dynamism are required.
|
|
|
|
## How does Codon compare to...
|
|
|
|
- **CPython?** Codon tries to follow CPython's syntax, semantics and APIs as
|
|
closely as possible, aside from a few cases where Codon differs from CPython for
|
|
performance reasons (one example being Codon's 64-bit `int` vs. CPython's arbitrary-
|
|
width `int`). Performance-wise, speedups over CPython are usually on the order of 10-100x.
|
|
|
|
- **Numba?** While Codon does offer a JIT decorator similar to Numba's, Codon is in
|
|
general an ahead-of-time compiler that compiles end-to-end programs to native code.
|
|
It also supports compilation of a much broader set of Python constructs and libraries.
|
|
|
|
- **PyPy?** PyPy strives to effectively be a drop-in replacement for CPython, whereas
|
|
Codon differs in a few places in order to eliminate any dynamic runtime or virtual
|
|
machine, and thereby attain much better performance.
|
|
|
|
- **C++?** Codon often generates the same code as an equivalent C or C++ program. Codon
|
|
can sometimes generate *better* code than C/C++ compilers for a variety of reasons, such
|
|
as better container implementations, the fact that Codon does not use object files and
|
|
inlines all library code, or Codon-specific compiler optimizations that are not performed
|
|
with C or C++.
|
|
|
|
- **Julia?** Codon's compilation process is actually much closer to C++ than to Julia. Julia
|
|
is a dynamically-typed language that performs type inference as an optimization, whereas
|
|
Codon type checks the entire program ahead of time. Codon also tries to circumvent the learning
|
|
curve of a new language by adopting Python's syntax and semantics.
|
|
|
|
You can see results from [Codon's benchmark suite](https://github.com/exaloop/codon/tree/develop/bench)
|
|
suite at [exaloop.io/benchmarks](https://exaloop.io/benchmarks).
|
|
More benchmarks can be found in the [2019 paper](https://dl.acm.org/doi/10.1145/3360551)
|
|
on bioinformatics-specific use cases (note that the name used in that paper is that of Codon's predecessor,
|
|
"Seq").
|
|
|
|
## I want to use Codon, but I have a large Python codebase I don't want to port.
|
|
|
|
You can use Codon on a per-function basis via the [`@codon.jit` decorator](../interop/decorator.md),
|
|
which can be used within Python codebases. This will compile only the annotated functions
|
|
and automatically handle data conversions to and from Codon. It also allows for
|
|
the use of any Codon-specific modules or extensions, such as multithreading.
|
|
|
|
## What about interoperability with other languages and frameworks?
|
|
|
|
Interoperability is and will continue to be a priority for Codon.
|
|
We don't want using Codon to render you unable to use all the other great frameworks and
|
|
libraries that exist. Codon supports full interoperability with Python and C/C++.
|
|
|
|
## Does Codon use garbage collection?
|
|
|
|
Yes, Codon uses the [Boehm garbage collector](https://github.com/ivmai/bdwgc).
|
|
|
|
## Codon doesn't support Python module X or function Y.
|
|
|
|
While Codon covers a sizeable subset of Python's standard library, it does not yet cover
|
|
every function from every module. Note that missing functions can still be called through
|
|
Python via `from python import`. Many of the functions that lack Codon-native implementations
|
|
(e.g. I/O or OS related functions) will generally also not see substantial speedups from Codon.
|
|
|
|
## Codon is no faster than Python for my application.
|
|
|
|
Applications that spend most of their time in C-implemented library code generally do not
|
|
see substantial performance improvements in Codon. Similarly, applications that are I/O or
|
|
network-bound will have the same bottlenecks in Codon.
|
|
|
|
## Codon is slower than Python for my application.
|
|
|
|
Please report any cases where Codon is noticeably slower than Python as bugs on our
|
|
[issue tracker](https://github.com/exaloop/codon/issues).
|
|
|
|
# Usage
|
|
|
|
## Is Codon free?
|
|
|
|
Codon is and always will be free for non-production use. That means you can use Codon
|
|
freely for personal, academic, or other non-commercial applications.
|
|
|
|
## Is Codon open source?
|
|
|
|
Codon is licensed under the [Business Source License (BSL)](https://mariadb.com/bsl11/), which
|
|
means its source code is publicly available and it's free for non-production use. The BSL
|
|
is technically *not* an "open source" license, although in many circumstances you can still treat
|
|
Codon as you would any other open source project. Importantly, as per the BSL, each version of
|
|
Codon converts to an actual open source license (specifically, [Apache](https://www.apache.org/licenses/LICENSE-2.0))
|
|
after 3 years.
|
|
|
|
## How can I use Codon for production or commercial use?
|
|
|
|
Please reach out to [info@exaloop.io](mailto:info@exaloop.io) to inquire about about a
|
|
production-use license.
|
|
|
|
# Contributing
|
|
|
|
## Does Codon accept outside contributions?
|
|
|
|
Absolutely, we'd be delighted to accept any contributions in the form of issues, bug reports,
|
|
feature requests or pull requests.
|
|
|
|
## I want to contribute. Where do I start?
|
|
|
|
If you have a specific feature or use case in mind, here is a quick breakdown of the codebase
|
|
to help provide a sense of where to look first:
|
|
|
|
- [`codon/`](https://github.com/exaloop/codon/tree/develop/codon): compiler code
|
|
- [`codon/parser/`](https://github.com/exaloop/codon/tree/develop/codon/parser):
|
|
parser and type checker code: this is the first step of compilation
|
|
- [`codon/sir/`](https://github.com/exaloop/codon/tree/develop/codon/sir):
|
|
Codon IR and optimizations: the second step of compilation
|
|
- [`codon/sir/llvm/`](https://github.com/exaloop/codon/tree/develop/codon/sir/llvm):
|
|
conversion from Codon IR to LLVM IR and machine code: the last step of compilation
|
|
- [`codon/runtime/`](https://github.com/exaloop/codon/tree/develop/codon/runtime):
|
|
runtime library: used during execution
|
|
- [`stdlib/`](https://github.com/exaloop/codon/tree/develop/stdlib): standard library code
|
|
|
|
You can also take a look at some of the [open issues](https://github.com/exaloop/codon/issues). If you
|
|
have any question or suggestions, please feel free to ask in [the forum](https://github.com/exaloop/codon/discussions).
|
|
|
|
## Is there a Contributor License Agreement (CLA)?
|
|
|
|
Yes, there is a CLA that is required to be agreed to before any pull requests are merged.
|
|
Please see [exaloop.io/cla.txt](https://exaloop.io/cla.txt) for more information. To agree to
|
|
the CLA, send an email with your GitHub username to [info@exaloop.io](mailto:info@exaloop.io).
|