poulp's specification

This document aims to provide a description of how poulp will work when it will be prouction-ready.

poulp.json

The poulp.json file contains some JSON defining the properties of a project. It is located at the root of the project.

It can contains the following keys.

name

The name of the project. It should only contain (small) letters, numbers or hyphens, and it must start with a letter.

"my-project" # correct
"my-project-123" # correct

"GTK+ App" # Incorrect : capitals, + and space
"42-the-meaning-of-life-etc" # Incorrect : begins with a number

This key is mandatory.

version

This is the version of your package. It should be a valid semantic version.

This key is mandatory.

description

This is just a short description of your package.

keywords

An array containing strings, which are the keywords of your package. It help people finding them when doing poulp search, and on the repositories websites using poulp server.

homepage

This is a string containing the URL of the projects website.

bugs

Specifies where to report bugs. It is an object, which can contain this fields.

license

The name of the license of your project.

author

The name of the author of the project. It could contain an email adress after the name, between < >.

contributors

A list of the peoples (string looking like the author field) who contributed to this project.

maintainers

A list of the peoples (string looking like the author field) who maintains this project.

files

The files to include at compilation.

repository

The URL of the projects repository, where we can find the source code.

vapi-dir

The path to a directory containing personal VAPIs.

output

Where to put the result of the compilation. Defaults to build/name-version (where name is the name of the project and version the version).

library

A boolean that tells us if this project is a library or not. If it is, it will be compiled in a special way, to make it reusable by everyone.

scripts

Some custom scripts, that can be run whit poulp run. It's an object containing the fields you want (their name will be used as the argument of poulp run). Each of those fields are arrays with the list of the command to run.

dependencies

The projects dependencies. It is an object where the keys are the name of the dependencies, and the value a range of versions. The name should be the same as the VAPI file name.

To see examples of version ranges, go to semver.

dev-dependencies

Same as dependencies, but will only be installed by people developing the project. For instance, it could a testing framework.

vala-version

The minimal Vala version to use with this project.

compiler-params

Some other arguments to gives to valac when building.

Commands

Each command listed here can be run with poulp command, where command is the command followed by its arguments.

[arg] is an optional argument.

search package

Search the package named package in the known repositories. It will display something like that.

package    0.1.0    Short description of the package.
other      0.2.3    Yet another package.

info package

Gives infos about package.

✓ Installed

Name          package
Version       0.1.0 (latest is 0.2.0, update with `poulp update package`)
Description   This is a package.
Author        John Doe
Contributors  Jane Doe, Foo Bar

Files         package.vapi, package.h, package.so, package.pc
Dependencies  other (0.2.3), foo (<2.1.0), bar (*)
Website       https://john.doe.eu/projects/package
Source code   https://john.doe.eu/git/package.git

pack [--zip|--gz]

Creates a .zip or .tar.gz file containing all the binaries of the project (.h, .vapi, .so, .dll, etc)

publish major|minor|patch --repo url [--no-changelog]

Pack the project (see pack above), creates a new version (update it in the manifest, git tag if the project uses git), and update the changelog with git log, if it was not manually done (this last behavior can be disabled with --no-changelog).

Then it post the new version on the repository at url.

Warning --repo and --no-changelog are not implemented yet.

build [--release]

Compiles your project using the options specified in the manifest.

gen output --template template

Creates a new file (output) from the template named template. output doesn't need to include any extension.

help [command]

Gives you help about poulp, or a specific command if command is specified.

init

An interactive tool to create a new project.

install [lib] [lib] [lib]...

Install all the specified libraries, or those present in libs in the manifest if none.

It clones the libraries, checkout to the most recent matching version, builds it and installs the result.

lint [--elementary|--gnome|--both]

Lints your code, following the specified convention (defautl is elementary).

repo [add|remove] [url]

Manages your remote repositories. If there is no argument, it just lists them.

If you do [add url], it registers the repo at url. And remove url unregisters the repository at url.

run script

It runs the script named script, previousy defined in the manifest.

update [lib] [lib] [lib]...

Updates your packages to the latest version.

Variables

poulp defines some environment varaibles when spawning a command. You can use them in output, compiler-params and your scripts.

Remote repositories organization

You can find a sample repository here.

The remote repositories just contains one file, named packages.json. It contains a list of all the packages available in this repository. It also contains another field, name, which is the name of the repository.

This file has an object, named packages which contains key-value pairs of packages (the name is the key, and the git repository the value).

Example package.json file

{
  "name": "A little poulp repository",
  "packages": {
    "foo": "https://git.foo.org/foo.git",
    "bar": "https://github.com/baz/bar",
    "hello": "https://gitlab.com/hey/hello"
  }
}

It is planed to make it possible for package to install templates, but not available yet.


Because it could be a little bit hard to manually manage a repository, we are working on a web interface to do it easily. But yet, you can just use a git repository.

Local organization

poulp stores local files in $POULP_DATA_DIR, which defaults to C:\ProgramData\poulp\ on Windows and /etc/poulp/ on other systems.

This directory contains a file named repos, which contains a list of all known repos (their URL to be exact), one per line.

Then, you have the projects and files folders, similar to those in a distant repository, but only with installed templates.