Corral

Pony dependency manager

Status

Corral is beta level software.

About Corral

Corral is a dependency management tool for Pony. Corral:

• Provides extensibility for VCS and Commands.
• Supports semver version constraints on dependencies.
• Supports transitive dependencies.
• Supports revision locking on dependencies using a lock.json file.
• Uses a distinct shared VCS repo pool from per-project dependency workspace tree.
• Uses the Pony process package for running external tools like Git and ponyc.

Design

See Corral Design for more details about the design of Corral. Ongoing questions and notes for future work can be found in Questions / Notes

Background

Check out Pony Package Dependency Management for a discussion of the research and requirements work behind Corral.

Installation

Pre-built binaries of Corral are available for Linux x86, MacOS x86, and Windows x86. To install on any of these platforms, use ponyup. For any other platform, you'll need to be build from source.

The following command is assuming that ponyup, our toolchain multiplexer, is already installed on your machine and is locatable by the name ponyup. If you don't have ponyup installed, please follow the ponyup installation instructions.

ponyup update corral release

Building From Source

See BUILD.md

Getting started using Corral

After installation, add Corral's current path to $PATH environment variable if you haven't already and follow these steps to create your first project using Corral.

Create a project

Make an empty folder and switch to this directory. This will be our example project to use Corral

mkdir myproject
cd myproject

Initialize Corral

It will create corral.json and lock.json files. At this moment they won't have much information since you haven't added any dependencies yet.

corral init

Add a dependency

This is the way to tell Corral that your project depends on this and you want to include it when building your project.

corral add github.com/ponylang/valbytes.git

Use a dependency

Create a file main.pony with following code.

use "valbytes"

actor Main
  new create(env: Env) =>
    var buf: ByteArrays = ByteArrays
    buf = buf + "!!" + "Hello," + " " + "World!"
    let greetings = buf.drop(2).string()
    env.out.print(greetings)

Get dependencies

The example Pony code is using ByteArrays type which is defined in the dependency which you have just added. Pony needs to have the source code of ByteArrays type to compile successfully. When corral update is run, Corral retrieves the source and makes it available when compiling the source code.

corral update

Build the project

Corral will now use this information to build the project. The command below act as a wrapper for ponyc

corral run -- ponyc

If there are no errors generated then an executable myproject will be created in the same folder.

You will also notice that there are two new folders _corral and _repos in your project folder now. They were generated by the corral update command. Please make sure to include them in your .gitignore file as there is no need to keep them in a versioning system since they are maintained by Corral itself.

Documentation

See DOCS.md