The Poac Book

Poac is a C++ package manager.

Poac can download project's dependencies, compile a project, create a package, and upload it to poac.dev.

poac.dev is a package registry which can be used to search packages and manage them.

Sections

Guide

A guide necessary for developing with Poac.

Reference

A reference covering more detailed features.

Commands

Details of commands implemented in Poac.

API Guidelines

Poac package API guidelines.

Guide

The guide necessary to develop with poac.

C++ is often considered to be a complicated language and shunned unconsciously by most people. It is thought that it is hard to construct a C++ environment, no definitive package manager, and the strange syntax of build systems such as CMake make us feel hesitant.

By developing a package manager and build system, which have an intuitively easy-to-use interface like npm and Cargo and make users be able to develop applications and libraries without being aware of CMake, developers will be able to focus on learning C++ without stumbling. I also plan to implement integration with many other build systems and package managers so that you can seamlessly switch a development environment.

Naming Background

Poac is originated from cpp but also designed to emphasize ease of typing and avoiding the burden being placed on only one hand as Poac will be entered many times as a command. The ergonomically optimized name prevents you from leading to tenosynovitis.

As I mentioned before, C++ is often avoided being selected for product development; however, I would like to disseminate C++ as a fun language through Poac. Amemiya and Mizutani argue that the /p/ sound gives the brightest and softest impression (157).¹ Accordingly, I believe Poac would likewise provide a bright and soft impression.

Amemiya, T., & Mizutani, S. (2006). On the Basic Affective Dimensions of Japanese Onomatopoeia and the Basic Level of Japanese Phonesthemes. 関西大学社会学部紀要, 37(2), 139–166. https://hdl.handle.net/10112/12311

Creating a new project

Use this command when you start a new poac project.

$ poac create hello_world
     Created binary (application) `hello_world` package

If you want to integrate your existing project with Poac, use the init command:
your-pj/$ poac init
     Created binary (application) `your-pj` package
This command just creates a poac.toml file not to let your project break.

Install dependencies

Like Cargo for Rust does, Poac installs dependencies at build time. However, Poac does not support weired specifiers for versions, such as ~ and ^. You can specify dependencies like:

poac.toml

[dependencies]
"boost/bind" = ">=1.64.0 and <2.0.0"

We regularly avoid auto updating packages to major versions which bring breaking changes, but minor and patch are acceptable.

If you would use a specific version, you can write the version as following:
[dependencies]
"boost/bind" = "1.66.0"

After editing poac.toml, executing the build command will install the package and its dependencies.

hello_world/$ poac build
 Downloading packages ...
  Downloaded boost/bind v1.66.0
  Downloaded boost/core v1.66.0
  Downloaded boost/assert v1.66.0
  Downloaded boost/config v1.66.0
   Compiling 1/1: hello_world v0.1.0 (/Users/ken-matsui/hello_world)
    Finished debug target(s) in 0.70s

To use this dependency, update the main.cpp file.

src/main.cpp

#include <iostream>
#include <boost/bind.hpp>
int f(int a, int b) {
  return a + b;
}
int main(int argc, char** argv) {
  std::cout << boost::bind(f, 5, _1)(10) << std::endl;
}

You can now run this source code:

hello_world/$ poac run
   Compiling 1/1: hello_world v0.1.0 (/Users/ken-matsui/hello_world)
    Finished debug target(s) in 0.50s
     Running `/Users/ken-matsui/hello_world/poac_output/debug/hello_world`
15

We currently support building a project with header-only dependencies. Building with build-required dependencies will be soon supported.

Introduce to Existing Projects

If you want to integrate your existing project with Poac, use the init command:

your-pj/$ poac init
     Created binary (application) `your-pj` package

This command just creates a poac.toml file not to let your project break.

Poac currently supports two types of dependencies: dependencies and dev-dependencies.

At build time, Poac will install these dependencies.

Dependencies

These dependencies are exposed to other packages which depend on this package.

[dependencies]
"boost/config": ">=1.64.0 and <2.0.0"

Development dependencies

Development dependencies are used for internal use, such as tests, examples, and benchmarks. These dependencies are not propagated to other packages which depend on this package.

[dev-dependencies]
"boost/predef" = ">=1.64.0 and <2.0.0"

Package Layout

Poac will support this structure: https://stackoverflow.com/a/2360780.