mirror of https://github.com/exaloop/codon.git
Update docs
A. R. Shajii
parent
6dd6503ec4
commit
44af203846
14
README.md
14
README.md
|
|
@ -3,20 +3,20 @@
|
|||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/exaloop.io/codon/actions?query=branch%3Adevelop">
|
||||
<img src="https://github.com/exaloop.io/codon/workflows/Codon%20CI/badge.svg?branch=develop"
|
||||
<a href="https://github.com/exaloop/codon/actions/workflows/ci.yml">
|
||||
<img src="https://github.com/exaloop/codon/actions/workflows/ci.yml/badge.svg"
|
||||
alt="Build Status">
|
||||
</a>
|
||||
<a href="https://gitter.im/seq-lang/seq?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge">
|
||||
<img src="https://badges.gitter.im/Join%20Chat.svg"
|
||||
alt="Gitter">
|
||||
</a>
|
||||
<a href="https://github.com/exaloop.io/codon/releases/latest">
|
||||
<img src="https://img.shields.io/github/v/release/exaloop.io/codon?sort=semver"
|
||||
<a href="https://github.com/exaloop/codon/releases/latest">
|
||||
<img src="https://img.shields.io/github/v/release/exaloop/codon?sort=semver"
|
||||
alt="Version">
|
||||
</a>
|
||||
<a href="https://github.com/exaloop.io/codon/blob/master/LICENSE">
|
||||
<img src="https://img.shields.io/github/license/exaloop.io/codon"
|
||||
<a href="https://github.com/exaloop/codon/blob/master/LICENSE">
|
||||
<img src="https://img.shields.io/github/license/exaloop/codon"
|
||||
alt="License">
|
||||
</a>
|
||||
</p>
|
||||
|
|
@ -112,4 +112,4 @@ See [Building from Source](docs/sphinx/build.rst).
|
|||
|
||||
## Documentation
|
||||
|
||||
Please check [docs.exaloop.io](https://docs.exaloop.io) for in-depth documentation.
|
||||
Please check [docs.codon.dev](https://docs.codon.dev) for in-depth documentation.
|
||||
|
|
|
|||
|
|
@ -21,8 +21,8 @@ sys.path.insert(0, os.path.abspath("./_ext"))
|
|||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = u'Codon'
|
||||
copyright = u'2019-2021, codon'
|
||||
author = u'codon'
|
||||
copyright = u'2019-2021, Exaloop, Inc.'
|
||||
author = u'exaloop'
|
||||
|
||||
# The short X.Y version
|
||||
version = u'0.11'
|
||||
|
|
|
|||
|
|
@ -47,13 +47,13 @@ Converting types
|
|||
The following table shows the conversions between Codon and C/C++ types:
|
||||
|
||||
============ ============
|
||||
Codon C/C++
|
||||
**Codon** **C/C++**
|
||||
------------ ------------
|
||||
``int`` ``int64_t``
|
||||
``int`` ``long`` or ``int64_t``
|
||||
``float`` ``double``
|
||||
``bool`` ``bool``
|
||||
``byte`` ``int8_t``
|
||||
``str`` ``{int64_t, char*}``
|
||||
``byte`` ``char`` or ``int8_t``
|
||||
``str`` ``{int64_t, char*}`` (length and data)
|
||||
``class`` Pointer to corresponding tuple
|
||||
``@tuple`` Struct of fields
|
||||
============ ============
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
**Codon** - a high-performance Python implementation
|
||||
====================================================
|
||||
**Codon** - a high-performance Python compiler
|
||||
==============================================
|
||||
|
||||
What is Codon?
|
||||
--------------
|
||||
|
||||
Codon is a high-performance Python implementation that compiles Python code to native machine code without any runtime overhead.
|
||||
Codon is a high-performance Python compiler that compiles Python code to native machine code without any runtime overhead.
|
||||
The Codon framework grew out of the `Seq <https://seq-lang.org>`_ project; while Seq focuses on genomics and bioinformatics, Codon
|
||||
can be applied in a number of different areas and is extensible via a plugin system.
|
||||
|
||||
|
|
@ -24,8 +24,9 @@ Questions, comments or suggestions? Visit our `Gitter chatroom <https://gitter.i
|
|||
:maxdepth: 1
|
||||
|
||||
intro
|
||||
tutorial/index
|
||||
primer
|
||||
parallel
|
||||
pipelines
|
||||
python
|
||||
embed
|
||||
build
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@ Pre-built binaries for Linux and macOS on x86_64 are available alongside `each r
|
|||
|
||||
.. code-block:: bash
|
||||
|
||||
/bin/bash -c "$(curl -fsSL https://seq-lang.org/install.sh)"
|
||||
/bin/bash -c "$(curl -fsSL https://codon.dev/install.sh)"
|
||||
|
||||
This will install Codon in a new ``.codon`` directory within your home directory.
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,63 @@
|
|||
Pipelines
|
||||
=========
|
||||
|
||||
Codon extends the core Python language with a pipe operator. You can chain multiple functions and generators to form a pipeline.
|
||||
Pipeline stages can be regular functions or generators. In the case of standard functions, the function is simply applied to the
|
||||
input data and the result is carried to the remainder of the pipeline, akin to F#'s functional piping. If, on the other hand, a
|
||||
stage is a generator, the values yielded by the generator are passed lazily to the remainder of the pipeline, which in many ways
|
||||
mirrors how piping is implemented in Bash. Note that Codon ensures that generator pipelines do not collect any data unless explicitly
|
||||
requested, thus allowing the processing of terabytes of data in a streaming fashion with no memory and minimal CPU overhead.
|
||||
|
||||
.. code:: python
|
||||
|
||||
def add1(x):
|
||||
return x + 1
|
||||
|
||||
2 |> add1 # 3; equivalent to add1(2)
|
||||
|
||||
def calc(x, y):
|
||||
return x + y**2
|
||||
2 |> calc(3) # 11; equivalent to calc(2, 3)
|
||||
2 |> calc(..., 3) # 11; equivalent to calc(2, 3)
|
||||
2 |> calc(3, ...) # 7; equivalent to calc(3, 2)
|
||||
|
||||
def gen(i):
|
||||
for i in range(i):
|
||||
yield i
|
||||
|
||||
5 |> gen |> print # prints 0 1 2 3 4 separated by newline
|
||||
range(1, 4) |> iter |> gen |> print(end=' ') # prints 0 0 1 0 1 2 without newline
|
||||
[1, 2, 3] |> print # prints [1, 2, 3]
|
||||
range(100000000) |> print # prints range(0, 100000000)
|
||||
range(100000000) |> iter |> print # not only prints all those numbers, but it uses almost no memory at all
|
||||
|
||||
Codon will chain anything that implements ``__iter__``, and the compiler will optimize out generators whenever possible. Combinations
|
||||
of pipes and generators can be used to implement efficient streaming pipelines.
|
||||
|
||||
.. caution::
|
||||
The Codon compiler may perform optimizations that change the order of elements passed through a pipeline.
|
||||
Therefore, it is best to not rely on order when using pipelines. If order needs to be maintained, consider
|
||||
using a regular loop or passing an index alongside each element sent through the pipeline.
|
||||
|
||||
Parallel pipelines
|
||||
------------------
|
||||
|
||||
CPython and many other implementations alike cannot take advantage of parallelism due to the infamous global interpreter lock, a mutex
|
||||
that prevents multiple threads from executing Python bytecode at once. Unlike CPython, Codon has no such restriction and supports full
|
||||
multithreading. To this end, Codon supports a *parallel* pipe operator ``||>``, which is semantically similar to the standard pipe
|
||||
operator except that it allows the elements sent through it to be processed in parallel by the remainder of the pipeline. Hence, turning
|
||||
a serial program into a parallel one often requires the addition of just a single character in Codon. Further, a single pipeline can
|
||||
contain multiple parallel pipes, resulting in nested parallelism.
|
||||
|
||||
.. code:: python
|
||||
|
||||
range(100000) |> iter ||> print # prints all these numbers, probably in random order
|
||||
range(100000) |> iter ||> process ||> clean # runs process in parallel, and then cleans data in parallel
|
||||
|
||||
Codon will automatically schedule the ``process`` and ``clean`` functions to execute as soon as possible. You can control the number of
|
||||
threads via the ``OMP_NUM_THREADS`` environment variable.
|
||||
|
||||
Internally, the Codon compiler uses an OpenMP task backend to generate code for parallel pipelines. Logically, parallel pipe operators are
|
||||
similar to parallel-for loops: the portion of the pipeline after the parallel pipe is outlined into a new function that is called by the
|
||||
OpenMP runtime task spawning routines (as in ``#pragma omp task`` in C++), and a synchronization point (``#pragma omp taskwait``) is added
|
||||
after the outlined segment.
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
Language Primer
|
||||
===============
|
||||
|
||||
If you know Python, you already know 95% of Codon. The following primer
|
||||
If you know Python, you already know 99% of Codon. The following primer
|
||||
assumes some familiarity with Python or at least one "modern"
|
||||
programming language (QBASIC doesn't count).
|
||||
|
||||
|
|
@ -21,8 +21,8 @@ For example, with a ``brew``-installed Python 3.9 on macOS, this might be
|
|||
|
||||
Note that only Python versions 3.6 and later are supported.
|
||||
|
||||
from python import
|
||||
------------------
|
||||
``from python import``
|
||||
----------------------
|
||||
|
||||
Let's say we have a Python function defined in *mymodule.py*:
|
||||
|
||||
|
|
@ -41,8 +41,8 @@ call and return types:
|
|||
|
||||
(Be sure the ``PYTHONPATH`` environment variable includes the path of *mymodule.py*!)
|
||||
|
||||
@python
|
||||
-------
|
||||
``@python``
|
||||
-----------
|
||||
|
||||
Codon programs can contain functions that will be executed by Python via ``pydef``:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +0,0 @@
|
|||
Tutorial
|
||||
========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
setup
|
||||
primer
|
||||
pipelines
|
||||
|
|
@ -1,52 +0,0 @@
|
|||
Pipelines
|
||||
=========
|
||||
|
||||
Pipelines
|
||||
---------
|
||||
|
||||
Codon extends the core Python language with a pipe operator. You can chain multiple functions and generators to form a pipeline. Pipeline stages can be regular functions or generators. In the case of standard functions, the function is simply applied to the input data and the result is carried to the remainder of the pipeline, akin to F#'s functional piping. If, on the other hand, a stage is a generator, the values yielded by the generator are passed lazily to the remainder of the pipeline, which in many ways mirrors how piping is implemented in Bash. Note that Codon ensures that generator pipelines do not collect any data unless explicitly requested, thus allowing the processing of terabytes of data in a streaming fashion with no memory and minimal CPU overhead.
|
||||
|
||||
.. code:: python
|
||||
|
||||
def add1(x):
|
||||
return x + 1
|
||||
|
||||
2 |> add1 # 3; equivalent to add1(2)
|
||||
|
||||
def calc(x, y):
|
||||
return x + y**2
|
||||
2 |> calc(3) # 11; equivalent to calc(2, 3)
|
||||
2 |> calc(..., 3) # 11; equivalent to calc(2, 3)
|
||||
2 |> calc(3, ...) # 7; equivalent to calc(3, 2)
|
||||
|
||||
def gen(i):
|
||||
for i in range(i):
|
||||
yield i
|
||||
|
||||
5 |> gen |> print # prints 0 1 2 3 4 separated by newline
|
||||
range(1, 4) |> iter |> gen |> print(end=' ') # prints 0 0 1 0 1 2 without newline
|
||||
[1, 2, 3] |> print # prints [1, 2, 3]
|
||||
range(100000000) |> print # prints range(0, 100000000)
|
||||
range(100000000) |> iter |> print # not only prints all those numbers, but it uses almost no memory at all
|
||||
|
||||
Codon will chain anything that implements ``__iter__``; however, use
|
||||
generators as much as possible because the compiler will optimize out
|
||||
generators whenever possible. Combinations of pipes and generators can be
|
||||
used to implement efficient streaming pipelines.
|
||||
|
||||
.. caution::
|
||||
The Codon compiler may perform optimizations that change the order of elements passed through a pipeline. Therefore, it is best to not rely on order when using pipelines. If order needs to be maintained, consider using a regular loop or passing an index alongside each element sent through the pipeline.
|
||||
|
||||
Parallel Pipelines
|
||||
------------------
|
||||
|
||||
CPython and many other implementations alike cannot take advantage of parallelism due to the infamous global interpreter lock, a mutex that protects accesses to Python objects, preventing multiple threads from executing Python bytecode at once. Unlike CPython, Codon has no such restriction and supports full multithreading. To this end, Codon supports a *parallel* pipe operator ``||>``, which is semantically similar to the standard pipe operator except that it allows the elements sent through it to be processed in parallel by the remainder of the pipeline. Hence, turning a serial program into a parallel one often requires the addition of just a single character in Codon. Further, a single pipeline can contain multiple parallel pipes, resulting in nested parallelism.
|
||||
|
||||
.. code:: python
|
||||
|
||||
range(100000) |> iter ||> print # prints all these numbers, probably in random order
|
||||
range(100000) |> iter ||> process ||> clean # runs process in parallel, and then cleans data in parallel
|
||||
|
||||
Codon will automatically schedule the ``process`` and ``clean`` functions to execute as soon as possible. You can control the number of threads via the ``OMP_NUM_THREADS`` environment variable.
|
||||
|
||||
Internally, the Codon compiler uses an OpenMP task backend to generate code for parallel pipelines. Logically, parallel pipe operators are similar to parallel-for loops: the portion of the pipeline after the parallel pipe is outlined into a new function that is called by the OpenMP runtime task spawning routines (as in ``#pragma omp task`` in C++), and a synchronization point (``#pragma omp taskwait``) is added after the outlined segment. Lastly, the entire program is implicitly placed in an OpenMP parallel region (``#pragma omp parallel``) that is guarded by a "single" directive (``#pragma omp single``) so that the serial portions are still executed by one thread (this is required by OpenMP as tasks must be bound to an enclosing parallel region).
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
Setup
|
||||
=====
|
||||
|
||||
Installation
|
||||
------------
|
||||
|
||||
Simple!
|
||||
|
||||
.. code:: bash
|
||||
|
||||
/bin/bash -c "$(curl -fsSL https://seq-lang.org/install.sh)"
|
||||
|
||||
If you want to use Python interop, you also need to point
|
||||
``CODON_PYTHON`` to the Python library (typically called
|
||||
``libpython3.9m.so`` or similar). The Codon repository contains a
|
||||
`Python script <https://github.com/exaloop/codon/blob/develop/test/python/find-python-library.py>`_
|
||||
that will identify and print the path to this library.
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Assuming that Codon was properly installed, you can use it as follows:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
codon run foo.codon # Compile and run foo.codon
|
||||
codon run -release foo.codon # Compile and run foo.codon with optimizations
|
||||
codon build -exe file.codon # Compile foo.codon to executable "foo"
|
||||
|
||||
Note that the ``-exe`` option requires ``clang`` to be installed, and
|
||||
the ``LIBRARY_PATH`` environment variable to point to the Codon runtime
|
||||
library (installed by default at ``~/.codon/lib/codon``).
|
||||
|
|
@ -2,9 +2,9 @@
|
|||
set -e
|
||||
set -o pipefail
|
||||
|
||||
SEQ_INSTALL_DIR=~/.seq
|
||||
OS=`uname -s | awk '{print tolower($0)}'`
|
||||
ARCH=`uname -m`
|
||||
CODON_INSTALL_DIR=~/.codon
|
||||
OS=$(uname -s | awk '{print tolower($0)}')
|
||||
ARCH=$(uname -m)
|
||||
|
||||
if [ "$OS" != "linux" ] && [ "$OS" != "darwin" ]; then
|
||||
echo "error: Pre-built binaries only exist for Linux and macOS." >&2
|
||||
|
|
@ -16,25 +16,25 @@ if [ "$ARCH" != "x86_64" ]; then
|
|||
exit 1
|
||||
fi
|
||||
|
||||
SEQ_BUILD_ARCHIVE=seq-$OS-$ARCH.tar.gz
|
||||
CODON_BUILD_ARCHIVE=codon-$OS-$ARCH.tar.gz
|
||||
|
||||
mkdir -p $SEQ_INSTALL_DIR
|
||||
cd $SEQ_INSTALL_DIR
|
||||
curl -L https://github.com/seq-lang/seq/releases/latest/download/$SEQ_BUILD_ARCHIVE | tar zxvf - --strip-components=1
|
||||
mkdir -p $CODON_INSTALL_DIR
|
||||
cd $CODON_INSTALL_DIR
|
||||
curl -L https://github.com/exaloop/codon/releases/latest/download/"$CODON_BUILD_ARCHIVE" | tar zxvf - --strip-components=1
|
||||
|
||||
EXPORT_COMMAND="export PATH=`pwd`/bin:\$PATH"
|
||||
EXPORT_COMMAND="export PATH=$(pwd)/bin:\$PATH"
|
||||
echo "PATH export command:"
|
||||
echo " $EXPORT_COMMAND"
|
||||
|
||||
update_profile () {
|
||||
if ! grep -F -q "$EXPORT_COMMAND" $1; then
|
||||
if ! grep -F -q "$EXPORT_COMMAND" "$1"; then
|
||||
read -p "Update PATH in $1? [y/n] " -n 1 -r
|
||||
echo
|
||||
|
||||
if [[ $REPLY =~ ^[Yy]$ ]]; then
|
||||
echo "Updating $1"
|
||||
echo >> $1
|
||||
echo "# Seq compiler path (added by install script)" >> $1
|
||||
echo "# Codon compiler path (added by install script)" >> $1
|
||||
echo $EXPORT_COMMAND >> $1
|
||||
else
|
||||
echo "Skipping."
|
||||
|
|
@ -62,5 +62,5 @@ else
|
|||
echo "Don't know how to update configuration file for shell $SHELL"
|
||||
fi
|
||||
|
||||
echo "Seq successfully installed at: `pwd`"
|
||||
echo "Open a new terminal session or update your PATH to use seqc"
|
||||
echo "Codon successfully installed at: $(pwd)"
|
||||
echo "Open a new terminal session or update your PATH to use codon"
|
||||
|
|
|
|||
Loading…
Reference in New Issue