project init (pi)
pi
is a command-line utility to initialize projects. It is written in rust.
It is intended to provide something like cookiecutter, but faster.
Reasons to use pi:
- You want to automate the process of starting a new project, for all your projects.
- You want project initialization that's quick
Reasons to use pi over cookiecutter:
- Templates are smaller. Define files you need in a
.toml
. - Fast. pi 30x faster than cookiecutter when rendering the sample vim plugin template.
- pi uses mustache, a logic-less language, for templates.
- pi can initialize a darcs, pijul, mercurial, or git repository inside your projects
- pi provides opinionated templates for many languages
- pi is extensible in Rust
Reasons to not use pi over cookiecutter:
- pi cannot fetch templates remotely.
- cookiecutter uses jinja templates, which are far more sophisticated.
- pi is newer and presumably more buggy
- cookiecutter is extensible in Python
Benchmarks (with Haskell's bench):
Tool | Language | Time (vim example plugin) | Time (rust library) |
---|---|---|---|
pi init | rust | 10.10 ms | 8.809 ms |
pi new | rust | 6.672 ms | 8.653 ms |
cookiecutter | python | 317.1 ms | 316.9 ms |
Installation
Binary releases
The easiest way for most users is simply to download the prebuilt binaries. You can find binaries for various platforms on the release page.
Cargo
First, install cargo. Then:
You will need to use the nightly release for this to work; if in doubt run
Use
pi
reads from $HOME/.pi_templates/
and your current directory. So, if you
place a template in the $HOME/.pi_templates/idris/
, you can initialize a
project anywhere with
There is a repo containing pi templates here.
You can also use pi with built-in templates, viz.
Currently pi has Rust, Haskell, Vimscript, Idris, Julia, Elm, and Python templates built-in.
Configuration
Global configuration is via the $HOME/.pi.toml
file. The following is an example:
= "BSD3" # set default license to BSD3
= "git" # initialize new repositories with git
= "0.1.0" # start new projects at version 0.1.0
[]
= "Vanessa McHale"
= "vanessa.mchale@reconfigure.io"
= "vmchale"
# put any custom keys you want under a [[user]] table
[[]]
= "https://vmchale.com"
Project-specific config lives in $PROJECT_NAME/template.toml
. The following is
an example for a vim plugin:
= "BSD3" # overrides global value if set
= true # add README.md
[]
= ["syntax/{{ project }}.vim","plugin/{{ project }}.vim","doc/{{ project }}.txt"] # blank files
= ["doc","syntax","plugin"]
= ["vimball.txt"] # files to be processed
[]
= "0.1.0"
= "darcs"
# put any custom keys you want below [[user]]
[[]]
= "vmchale"
This will generate the following directory structure:
vim-plugin
├── LICENSE
├── README.md
├── doc
│ └── vim-plugin.txt
├── plugin
│ └── vim-plugin.vim
├── syntax
│ └── vim-plugin.vim
└── vimball.txt
Templates
pi
uses mustache for templating, via the
rustache crate.
You can find examples and help on the mustache page, or you can my look at the example repo.