ponyc  0.28.1
About: Pony is an object-oriented, actor-model, capabilities-secure, high performance programming language.
  Fossies Dox: ponyc-0.28.1.tar.gz  ("inofficial" and yet experimental doxygen-generated source code documentation)  

ponyc Documentation

Some Fossies usage hints in advance:

  1. To see the Doxygen generated documentation please click on one of the items in the steelblue colored "quick index" bar above or use the side panel at the left which displays a hierarchical tree-like index structure and is adjustable in width.
  2. If you want to search for something by keyword rather than browse for it you can use the client side search facility (using Javascript and DHTML) that provides live searching, i.e. the search results are presented and adapted as you type in the Search input field at the top right.
  3. Doxygen doesn't incorporate all member files but just a definable subset (basically the main project source code files that are written in a supported language). So to search and browse all member files you may visit the Fossies
  4. ponyc-0.28.1.tar.gz contents page and use the Fossies standard member browsing features (also with source code highlighting and additionally with optional code folding).
README.md

Backers on Open Collective Sponsors on Open Collective

Contributors

This project exists thanks to all the people who contribute. [Contribute].

Backers

Thank you to all our backers! 🙏 [Become a backer]

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

Getting help

Need help? Not to worry, we have you covered.

We have a couple resources designed to help you learn, we suggest starting with the tutorial and from there, moving on to the Pony Patterns book. Additionally, standard library documentation is available online.

If you are looking for an answer "right now", we suggest you give our Zulip community a try. Whatever your question is, it isn't dumb, and we won't get annoyed.

Think you've found a bug? Check your understanding first by writing the mailing list. Once you know it's a bug, open an issue.

Trying it online

If you want a quick way to test or run code, checkout the Playground.

Editor support

Installation

Pony supports LLVM 3.9 and on an experimental basis it supports LLVM 4.0 and 5.0. In addition, support for OpenSSL 1.1.0 was recently added for systems such as the Debian Stretch and Arch Linux, see FAQ Compiling for additional information.

Pony's prerequisites for CPU platforms are:

Using Docker

Want to use the latest revision of Pony source, but don't want to build from source yourself? You can run the ponylang/ponyc Docker container, which is created from an automated build at each commit to master.

You'll need to install Docker using the instructions here. Then you can pull the latest ponylang/ponyc image using this command:

Then you'll be able to run ponyc to compile a Pony program in a given directory, running a command like this:

If you're unfamiliar with Docker, remember to ensure that whatever path you provide for /path/to/my-code is a full path name and not a relative path, and also note the lack of a closing slash, /, at the end of the path name.

Note that if your host doesn't match the docker container, you'll probably have to run the resulting program inside the docker container as well, using a command like this:

If you're using docker-machine instead of native docker, make sure you aren't using an incompatible version of Virtualbox.

Docker for Windows

Pull the latest image as above.

Share a local drive (volume), such as c:, with Docker for Windows, so that they are available to your containers. (Refer to shared drives in the Docker for Windows documentation for details.)

Then you'll be able to run ponyc to compile a Pony program in a given directory, running a command like this:

Note the inserted drive letter. Replace with your drive letter as appropriate.

To run a program, run a command like this:

To compile and run in one step run a command like this:

Docker and AVX2 Support

By default, the Pony Docker image is compiled without support for AVX CPU instructions. For optimal performance on modern hardware, you should build your Pony installation from source.

Linux using an AppImage package (via Bintray)

For most Linux distributions released after RHEL 7, the release builds are packaged and available on Bintray (pony-language/ponyc-appimage/ponyc) as an AppImage.

The AppImage (www.appimage.org) format allow for an easy ability to use applications with minimal clutter added to your system. The applications are available in a single file and can be run after they're made executable. Additionally, AppImages allow for multiple versions of Pony to be used side by with no conflicts.

To install builds via AppImage, you need to go to Bintray and download the appropriate file for the version you want. After the file is downloaded, you need to make it executable using chmod.

DEB and AVX2 Support

By default, the Pony AppImage package is compiled without support for AVX CPU instructions. For optimal performance, you should build your Pony installation from source.

Linux using an RPM package (via COPR)

For Red Hat, CentOS, Oracle Linux, Fedora Linux, or OpenSuSE, the release builds are packaged and available on COPR (ponylang/ponylang).

Using yum for Red Hat, CentOS, Oracle Linux and other RHEL compatible systems:

See https://bugzilla.redhat.com/show_bug.cgi?id=1581675 for why epel-7 is required on the command line.

Using DNF for Fedora Linux:

Using Zypper for OpenSuSE Leap 15:

Using Zypper for OpenSuSE Tumbleweed:

RPM and AVX2 Support

By default, the Pony RPM package is compiled without support for AVX CPU instructions. For optimal performance, you should build your Pony installation from source.

Ubuntu and Debian Linux using a DEB package (via Bintray)

For Ubuntu and Debian Linux, the release builds are packaged and available on Bintray (pony-language/ponylang-debian).

Install packages to allow apt to use a repository over HTTPS:

Install builds via Apt (and install Ponylang's public key):

DEB and AVX2 Support

By default, the Pony DEB package is compiled without support for AVX CPU instructions. For optimal performance, you should build your Pony installation from source.

Linux Mint

All steps to install Pony in Linux Mint are the same from Ubuntu, but you must use the Ubuntu package base (xenial, bionic) instead of the Linux Mint release.

Install pre-requisites and add the correct apt repository:

The same AVX2 support restrictions apply.

Gentoo Linux

A live ebuild is also available in the overlay (dev-lang/pony-9999) and for Vim users there's app-vim/pony-syntax.

Linux using Linuxbrew

NixOS Linux or any OS using nix

"cannot find 'ld'" error

If you get an error when trying to use ponyc to compile pony source that looks like this:

you might have to install the ld-gold linker. It can typically be found by searching your distro's package repository for binutils-gold or just ld-gold.

Mac OS X using Homebrew

Windows using ZIP (via Bintray)

Windows users will need to install:

  • Visual Studio 2019, 2017 or 2015 (available here) or the Visual C++ Build Tools 2019, 2017 or 2015 (available here), and
    • If using Visual Studio 2015, install the Windows 10 SDK (available here).
    • If using Visual Studio 2017 or 2019, install the "Desktop Development with C++" workload.
    • If using Visual C++ Build Tools 2017 or 2019, install the "Visual C++ build tools" workload, and the "Visual Studio C++ core features" individual component.
    • If using Visual Studio 2017 or 2019, or Visual C++ Build Tools 2017 or 2019, make sure the latest Windows 10 SDK (10.x.x.x) for Desktop will be installed.

Once you have installed the prerequisites, you can download the latest ponyc release from bintray.

Building ponyc from source

First of all, you need a compiler with decent C11 support. The following compilers are supported, though we recommend to use the most recent versions.

  • GCC >= 4.7
  • Clang >= 3.4
  • MSVC >= 2015
  • XCode Clang >= 6.0

When building ponyc from sources the LLVM installed on your system is used by default. Optionally, you may also build ponyc with LLVM from sources.

Building ponyc using LLVM sources:

Prerequisites:

  • git >= 2.17, other versions may work but this is what has been tested.

Instructions:

To compile Pony using LLVM sources on Linux add -f Makefile-lib-llvm to any of the examples below. For instance on Ubuntu the standard command line is simply make, to build ponyc using LLVM from sources the command line is make -f Makefile-lib-llvm. Alternatively you can create a symlink from Makefile to Makefile-lib-llvm, ln -sf Makefile-lib-llvm Makefile, and no changes would be needed to the commands. You can specify llvm_target=llvm-6.0.0 on the command line and those sources will be used. For example make -f Makefile-lib-llvm llvm_target=llvm-6.0.0.

Typically you only need to build the LLVM sources once, as the make clean target does not cause the LLVM sources to be rebuilt. To rebuild everything use make -f Makefile-lib-llvm clean-all && make -f Makefile-lib-llvm. There is also a distclean target, make -f Makefle-lib-llvm distclean`, which will remove the llvm sources and they will be retrieved from the ponylang/llvm repo.

NOTE: If LLVM version < 5.0.0 is used, cpu feature avx512f is disabled automagically to avoid LLVM bug 30542 otherwise the compiler crashes during the optimization phase.

Changing the commit associated with LLVM_CFG=llvm-default.cfg

When LLVM_CFG is not specified or it is llvm-default.cfg the commit associated with the src submodule is checked out as the llvm source to be built. To change to a different commit, for instance tag llvmorg-8.0.0, simply clone ponyc and change lib/llvm/src to the desired commit:

git clone --recurse-submodules  https://github.com/<you>/ponyc
cd ponyc
git checkout -b update-lib-llvm-src-to-llvmorg-8.0.0
cd lib/llvm/src
git checkout llvmorg-8.0.0
cd ../../../

If you already have ponyc checked out update/init lib/llvm/src submodule, if it hasn't been fetched, and then go into lib/llvm/src and checkout the desired commit:

git submodule update --init
cd lib/llvm/src
git checkout llvmorg-8.0.0
cd ../../../

Debug/test ....

Now build and test using LLVM_CFG=llvm-default.cfg and any other appropriate parameters:

make -j12 LLVM_CFG=llvm-default.cfg default_pic=true default_ssl=openssl_1.1.0 -f Makefile-lib-llvm

When satisfied create a commit pushing to your repo:

git add lib/llvm/src
git commit -m "Update submodule lib/llvm/src to llvmorg-8.0.0"
git push origin update-lib-llvm-src-to-llvmorg-8.0.0

See the Submodule section of the git-scm book for more information.

Building on Linux

Get the pony source from GitHub (For information on setting up Git, see https://help.github.com/articles/set-up-git/):

Linux and OS X

Arch

Install pony dependencies:

pacman -S llvm make ncurses openssl pcre2 zlib

To build ponyc and compile and run helloworld:

Debian Sid

Install pony dependencies:

To build ponyc, compile and run helloworld:

Ubuntu Xenial

Add the LLVM apt repos to /etc/apt/sources.list. Open /etc/apt/sources.list and add the following lines to the end of the file:

deb http://apt.llvm.org/xenial/ llvm-toolchain-xenial-3.9 main
deb-src http://apt.llvm.org/xenial/ llvm-toolchain-xenial-3.9 main

Add the LLVM repo as a trusted source:

Clone the ponyc repo:

Build ponyc, compile and run helloworld:

Ubuntu Bionic

Clone the ponyc repo:

Build ponyc, compile and run helloworld:

Linux Mint

Instructions for Linux Mint are the same as the appropriate Ubuntu installation. However, an extra llvm-3.9-dev package is required for missing headers.

After installing the llvm package by following the appropriate steps for Ubuntu Trusty (Linux Mint 17), Xenial (Linux Mint 18), or Bionic (Linux Mint 19), install the extra headers:

Fedora (25)

To build ponyc, compile and run helloworld:

Fedora (26, 27, 28, Rawhide)

To build ponyc, compile and run helloworld:

CentOS/RHEL (7)

Install dependencies:

Using LLVM 3.9.1 from EPEL:

Using LLVM 3.9.1 from copr:

Using LLVM 5.0.1 from copr:

Using LLVM 4.0.1 from llvm-toolset-7 from SCL:

CentOS:

RHEL:

Enable the llvm collection before building:

To build ponyc, compile and run helloworld:

OpenSUSE (Leap 42.3)

To build ponyc, compile and run helloworld:

OpenSuSE (Leap 15, Tumbleweed)

NOTE: LLVM 3.9 doesn't seem to be available so these instructions install the default LLVM version available.

To build ponyc, compile and run helloworld:

Alpine (3.6, 3.7, Edge)

Install build tools/dependencies:

To build ponyc, compile and run helloworld:

Other Linux distributions

You need to have the development versions of the following installed:

  • LLVM 3.9.1
  • zlib
  • ncurses
  • pcre2
  • libssl

There is experimental support for LLVM 4.0.1 and 5.0.0, but this may result in decreased performance or crashes in generated applications.

If your distribution doesn't have a package for prce2, you will need to download and build it from source:

Finally to build ponyc, compile and run the hello world app:

Building on DragonFly

Pony previously worked on DragonFly, however, at this time, while it builds, it doesn't pass all tests. If you'd be interested in getting Pony working on DragonFly, have at it. You'll need the following dependencies:

First, install the required dependencies:

Building on FreeBSD

First, install the required dependencies:

  • Pony is currently supported on FreeBSD12 for amd64 (64-bit) using LLVM 7
  • The following packages, with their installation commands:

This will build ponyc and compile helloworld:

Building on OpenBSD

OpenBSD has been tested on OpenBSD 6.5.

First, install the required dependencies:

This will build ponyc and compile helloworld:

If you are on a 32-bit platform (e.g., armv7), change bits=64 to bits=32.

Building on Mac OS X

Linux and OS X

You'll need llvm 3.9.1 and the pcre2 library to build Pony. You can use either homebrew or MacPorts to install your dependencies.

There is experimental support for LLVM 4.0.1 or 5.0.0, but this may result in decreased performance or crashes in generated applications.

Installation via homebrew:

brew update
brew install llvm@3.9 pcre2 libressl

Installation via MacPorts:

sudo port install llvm-3.9 pcre2 libressl
sudo port select --set llvm mp-llvm-3.9

Launch the build with make after installing the dependencies:

make
./build/release/ponyc examples/helloworld

Building on Windows

Backers on Open Collective Sponsors on Open Collective Windows

Note: it may also be possible (as tested on build 14372.0 of Windows 10) to build Pony using the Ubuntu 14.04 instructions inside Bash on Ubuntu on Windows.

Building on Windows requires the following:

  • Visual Studio 2019, 2017 or 2015 (available here) or the Visual C++ Build Tools 2019, 2017 or 2015 (available here), and
    • If using Visual Studio 2015, install the Windows 10 SDK (available here).
    • If using Visual Studio 2017 or 2019, install the "Desktop Development with C++" workload.
    • If using Visual C++ Build Tools 2017 or 2019, install the "Visual C++ build tools" workload, and the "Visual Studio C++ core features" individual component.
    • If using Visual Studio 2017 or 2019, or Visual C++ Build Tools 2017 or 2019, make sure the latest Windows 10 SDK (10.x.x.x) for Desktop will be installed.
  • Python (3.6 or 2.7) needs to be in your PATH.

In a command prompt in the ponyc source directory, run the following:

make.bat configure

(You only need to run make.bat configure the first time you build the project.)

make.bat build test

This will automatically perform the following steps:

  • Download some pre-built libraries used for building the Pony compiler and standard library.
  • Build the pony compiler in the build/<config>-<llvm-version> directory.
  • Build the unit tests for the compiler and the standard library.
  • Run the unit tests.

You can provide the following options to make.bat when running the build or test commands:

  • --config debug|release: whether or not to build a debug or release build (release is the default).
  • --llvm <version>: the LLVM version to build against (3.9.1 is the default).

Note that you need to provide these options each time you run make.bat; the system will not remember your last choice.

Other commands include clean, which will clean a specified configuration; and distclean, which will wipe out the entire build directory. You will need to run make configure after a distclean.

Link-time optimizations provide a performance improvement. You should strongly consider turning on LTO if you build ponyc from source. It's off by default as it comes with some caveats:

  • If you aren't using clang as your linker, we've seen LTO generate incorrect binaries. It's rare but it can happen. Before turning on LTO you need to be aware that it's possible.

  • If you are on MacOS, turning on LTO means that if you upgrade your version of XCode, you will have to rebuild your Pony compiler. You won't be able to link Pony programs if there is a mismatch between the version of XCode used to build the Pony runtime and the version of XCode you currently have installed.

You can enable LTO when building the compiler in release mode. There are slight differences between platforms so you'll need to do a manual setup. LTO is enabled by setting lto to yes in the build command line:

If the build fails, you have to specify the LTO plugin for your compiler in the LTO_PLUGIN variable. For example:

Refer to your compiler documentation for the plugin to use in your case.

Building the runtime as an LLVM bitcode file

If you're compiling with Clang, you can build the Pony runtime as an LLVM bitcode file by setting runtime-bitcode to yes in the build command line:

Then, you can pass the --runtimebc option to ponyc in order to use the bitcode file instead of the static library to link in the runtime:

This functionality boils down to "super LTO" for the runtime. The Pony compiler will have full knowledge of the runtime and will perform advanced interprocedural optimisations between your Pony code and the runtime. If you're looking for maximum performance, you should consider this option. Note that this can result in very long optimisation times.

VirtualBox

Pony binaries can trigger illegal instruction errors under VirtualBox 4.x, for at least the x86_64 platform and possibly others.

Use VirtualBox 5.x to avoid possible problems.

You can learn more about AVX2 support.

Building Pony on Non-x86 platforms

On ARM platforms, the default gcc architecture specification used in the Makefile of native does not work correctly, and can even result in the gcc compiler crashing. You will have to override the compiler architecture specification on the make command line. For example, on a RaspberryPi2 you would say:

To get a complete list of acceptable architecture names, use the gcc command:

This will result in an error message plus a listing of all architecture types acceptable on your platform.