Important
Poac is still under development and may contain a bunch of bugs.
Poac (pronounced as /pəʊək/
) is a package manager and build system for C++ users, inspired by Cargo for Rust. Poac is designed as a structure-oriented build system, which means that as long as you follow Poac's designated project structure, you almost do not need configurations, much less a language to build, unlike CMake. If you do not like writing a bunch of configurations to build your project, Poac might be best suited. Currently, the supported project structure can be known by looking at this repository since Poac can build itself.
Please visit poac.dev and The Poac Book for more details.
By using Poac, you can create a C++ project, build sources, and execute an application:
You can get started with just a few commands as the demo shows. Let's create a new Poac project:
you:~$ poac new hello_world
Created binary (application) `hello_world` package
Now, you can use the poac run
command to run your application:
you:~$ cd hello_world
you:~/hello_world$ poac run
Compiling src/main.cc
Linking hello_world
Finished debug target(s) in 0.45386s
Running poac-out/debug/hello_world
Hello, world!
Linux | macOS |
---|---|
Since packages through these providers may not be maintained by Poac owners, install them at your own risk.
It is important to verify the package name and copy it accurately to prevent typosquatting attacks. You can check the correct name by following the link in Packaging status
(Repology).
brew install poac
sudo port install poac
If your environment is not included in the released packages, you have to build Poac from the source. You will require the following compilers, commands, and libraries:
- GCC:
11
or later - Clang:
15
or later - Apple Clang: provided by
macOS Monterey (12)
or later
- make
- pkg-config
- find
- grep
- mkdir
- rm
- libgit2
When running Make, the following libraries will be installed automatically.
- toml11:
9086b11
or later- requires this commit
- awaiting the next release above
v3.7.1
Once you have all the necessary requirements in place, you can build Poac by the following commands:
git clone https://github.com/poac-dev/poac.git
cd poac
make RELEASE=1 install
- C++ compiler
- Make
- pkg-config
- mkdir
- echo
- Git (for Git dependencies)
- cpplint (for
poac lint
) - clang-format (for
poac fmt
)
The poac new
command lets you start a new Poac project:
you:~$ poac new hello_world
Created binary (application) `hello_world` package
Tip
If you want to integrate your existing project with Poac, use the init
command:
you:~/your-pj$ poac init
Created binary (application) `your-pj` package
This command just creates a poac.toml
file not to break your project.
In most cases, you want to execute the generated binary as well as build the project.
you:~/hello_world$ poac run
Compiling src/main.cc
Linking hello_world
Finished debug target(s) in 0.45386s
Running poac-out/debug/hello_world
Hello, world!
If you just want to build it, run the build
command:
you:~/hello_world$ poac build
Finished debug target(s) in 0.00866317s
Poac uses a cache since we executed the command with no changes.
Tip
To use a different compiler, you can export a CXX
environmental variable:
export CXX=g++-13
Like Cargo does, Poac installs dependencies at build time. Poac currently supports only Git dependencies. You can specify dependencies like:
poac.toml
[dependencies]
"ToruNiina/toml11" = { git = "https://github.com/ToruNiina/toml11.git", rev = "846abd9a49082fe51440aa07005c360f13a67bbf" }
After editing poac.toml
, executing the build
command will install the package and its dependencies.
you:~/hello_world$ poac build
Downloaded ToruNiina/toml11 846abd9a49082fe51440aa07005c360f13a67bbf
Compiling src/main.cc
Linking hello_world
Finished debug target(s) in 0.70s
Warning
Poac currently supports building a project with header-only dependencies. Building with build-required dependencies will be soon supported.
You can write unit tests in any source files within the src
directory. Create a new file like:
src/Lib.cc
int add(int a, int b) {
return a + b;
}
#ifdef POAC_TEST
# include <cassert>
int main() {
assert(add(1, 2) == 3); // ok
assert(add(1, 2) == 4); // fail
}
#endif
Now, with the test
command, you can run tests defined within POAC_TEST
:
you:~/hello_world$ poac test
Compiling src/Lib.cc
Linking tests/test_Lib
Testing Lib
Assertion failed: (add(1, 2) == 4), function main, file Lib.cc, line 13.
make: *** [test] Abort trap: 6
Unit tests with the POAC_TEST
macro are useful when testing private functions. Integration testing with the tests
directory has not yet been implemented.
Linting source code is essential to protect its quality. Poac supports linting your project by the lint
command:
you:~/hello_world$ poac lint
Linting hello_world
src/main.cc:0: No copyright message found. You should have a line: "Copyright [year] <Copyright Owner>" [legal/copyright] [5]
Done processing src/main.cc
Total errors found: 1
Error: `cpplint` exited with status 1
Tip
If you do not have cpplint
, install it with the following command:
pip install cpplint
The lint
command works without configurations, and Poac would automatically opt out of unwanted lints by adjusting to each project.
To customize the lint settings, try adding the [lint.cpplint]
key in your poac.toml
like this
or creating a CPPLINT.cfg
file in the repository root.
Poac also supports formatting your source code with clang-format
. Ensure having installed clang-format
before running this command.
you:~/hello_world$ poac fmt
Formatting hello_world
Note
This command automatically detects what files we need to format to avoid getting bothered by commands like:
$ # We need to avoid the `build` dir and such dirs ...
$ clang-format ./src/*.cpp -i
$ clang-format ./include/**/*.hpp -i
$ clang-format ./tests/**/*.cpp -i
$ ...
To customize the format settings, try creating a .clang-format
file to the repository root.
C++ is often considered a complex language and unconsciously avoided by many. The absence of a definitive package manager and the unfamiliar syntax of build systems like CMake make it seem difficult to set up a C++ environment, leaving people hesitant.
To simplify the process and allow users to develop applications and libraries without worrying about CMake, I created a package manager and build system with an intuitive interface, similar to Cargo. This allows developers to focus on learning C++ without any hindrances. Additionally, I aim to integrate with other build systems and package managers, providing a seamless transition between development environments.
Poac is originated from cpp
but designed to prioritize ease of typing and reduce strain on one hand as it will be frequently used as a command. Its name is ergonomically optimized to prevent the development of tenosynovitis.
Despite C++ often being overlooked for product development, I believe that Poac can help to promote it as a fun language. Amemiya and Mizutani argue that the sound of /p/
is associated with a bright and soft impression among Japanese consonants (157)1. In the same way, I believe that Poac's name can convey a similarly positive impression.
Please make sure to follow these steps:
poac lint
poac fmt
This project exists thanks to all the people who contribute.
Poac is licensed under the terms of the Apache License version 2.0.
Please see LICENSE for details.
Footnotes
-
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 ↩