Le mirroring des dépôts vers Github est maintenant natif dans Gitlab (et donc Framagit). Merci de passer à la fonction native pour que nous puissions couper notre solution maison. Détails sur https://docs.gitlab.com/ee/workflow/repository_mirroring.html#pushing-to-a-remote-repository (pensez à supprimer le webhook de notre solution maison).

SPEC.md 8.55 KB
Newer Older
Bat committed
1 2
# poulp's specification

Bat committed
3
*This document aims to provide a description of how poulp will work when it will be production-ready.*
Bat committed
4

Bat committed
5
## poulp.toml
Bat committed
6

Bat committed
7
The `poulp.toml` file contains some [TOML](https://github.com/toml-lang/toml) defining the properties of a project. It is located at the root of the project.
Bat committed
8 9 10 11 12 13 14

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.

Bat committed
15 16 17
```toml
name = "my-project" # correct
name = "my-project-123" # correct
Bat committed
18

Bat committed
19 20
name = "GTK+ App" # Incorrect : capitals, +, and space
name = "42-the-meaning-of-life-etc" # Incorrect : begins with a number
Bat committed
21 22
```

Bat committed
23
*This key is mandatory.*
Bat committed
24 25 26 27 28

### version

This is the version of your package. It should be a valid [semantic version](http://semver.org).

Bat committed
29
*This key is mandatory.*
Bat committed
30 31 32 33 34

### description

This is just a short description of your package.

Bat committed
35 36
### keywords

Bat committed
37
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](https://framagit.org/poulp/poulp-server).
Bat committed
38 39 40 41 42 43 44

### homepage

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

### bugs

Bat committed
45
Specifies where to report bugs. It is an table, which can contain this fields.
Bat committed
46 47 48 49 50 51

- `url`, the bug tracker URL ;
- `email`, an email adress where we can send bug reports.

### license

Bat committed
52
The name of the license of your project, or the path to the file containing its license.
Bat committed
53

Bat committed
54
### authors
Bat committed
55

Bat committed
56
The names of the authors of the project. They could contain an email adress after the name, between `<` `>`.
Bat committed
57 58 59 60 61 62 63

### files

The files to include at compilation.

### repository

Bat committed
64
The URL of the projects repository, where we can find the source code. It will be used when running `poulp publish`.
Bat committed
65

Bat committed
66
### vapi-dir
Bat committed
67 68 69 70 71

The path to a directory containing personal VAPIs.

### output

Bat committed
72
Where to put the result of the compilation. Defaults to `build/name-version` (where `name` is the name of the project and `version` its version).
Bat committed
73

74 75 76 77
### 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.

Bat committed
78 79
### scripts

Bat committed
80
Some custom scripts, that can be run whit `poulp run`. It's a table 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.
Bat committed
81

Bat committed
82
### dependencies
Bat committed
83

Bat committed
84
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.
Bat committed
85

Bat committed
86
To see examples of version ranges, go to [semver](https://framagit.org/Bat/semver).
Bat committed
87

Bat committed
88
### dev-dependencies
Bat committed
89

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

Bat committed
92
### vala-version
Bat committed
93

Bat committed
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
The Vala version to use with this project. It is also a semantic versionning range.

### features

Compiler features that can be enabled or disabled. This table contains only booleans (`true` means enables, `false` disabled). Available features are:

- fast-vapi, to generate fast `.vapi` files, without "absolute" symbols (e.g `using Gtk;` and `Button` instead of `Gtk.Button`)
- vapi-comments, to keep comments in `.vapi`
- debug, to make your project easily debuggable with `gdb`
- thread, to enable multithreading support in the compiler
- memory-profiler, to enable GLib memory profiler
- standard-packages, to disable packaging `glib-2.0`, `gobject-2.0` and `gmodule-2.0`
- assert, to disable `assert`
- checking, to enable `checking`
- deprecated, to allow the `[Deprecated]` attribute
- hide-internal, to mark `internal` symbols as `private` in C code (`internal` doesn't exist in C)
- experimental, to enable experimental features
- warnings, to turn off warnings
- fatal-warnings, if you want warnings to make your build failing
- since-check, to avoid checking if the symbol exists in local packages
- non-null, to ensure that nothing is never `null`
- gobject-tracing, to turn on GObject tracing
- version-header, if you want to write the valac version in the `.h` file
- c-warnings, to turn off c warnings
Bat committed
118 119

### compiler-params
Bat committed
120 121 122

Some other arguments to gives to `valac` when building.

Bat committed
123 124 125



Bat committed
126 127 128 129 130 131
## 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.

Bat committed
132
### search package
Bat committed
133 134 135 136 137 138 139 140

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.
```

Bat committed
141
### info package
Bat committed
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163

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)

Bat committed
164
### publish major|minor|patch --repo url [--no-changelog]
Bat committed
165

Bat committed
166
Pack the project (see `pack` above), creates a new version (update it in the manifest, `git tag` if the project uses `git`),
Bat committed
167 168 169 170
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`.

Bat committed
171 172
**Warning** `--repo` and `--no-changelog` are not implemented yet.

Bat committed
173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192
### 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.

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

Bat committed
195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
### 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.




Bat committed
216 217
# Variables

Bat committed
218
poulp defines some environment varaibles when spawning a command. You can use them in `output`, `compiler-params` and your scripts.
Bat committed
219 220 221 222 223 224 225 226

- `$PROJECT_NAME`, the name of your project;
- `$PROJECT_VERSION`, the version of your project;
- `$PROJECT_DESCRIPTION`, the description of your project;
- `$PROJECT_LICENSE`, the license of your project;
- `$PROJECT_HOMEPAGE`, the homepage of your project;
- `$PROJECT_OUTPUT`, the path to the output of your project;

Bat committed
227 228
# Remote repositories organization

Bat committed
229 230
*You can find a sample repository [here](https://gitlab.com/Bat41/poulp-repo-test/tree/master/dist).*

Bat committed
231
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.
Bat committed
232

Bat committed
233
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).
Bat committed
234

Bat committed
235
*Example `packages.json` file*
Bat committed
236

Bat committed
237 238 239 240 241 242 243 244 245
```
{
  "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"
  }
}
Bat committed
246 247
```

Bat committed
248
It is planed to make it possible for package to install templates, but not available yet.
Bat committed
249 250 251 252

----

Because it could be a little bit hard to manually manage a repository, we are [working on a web interface](https://framagit.org/valse/poulp-server) to do it easily. But yet, you can just use a git repository.
Bat committed
253 254 255



Bat committed
256
# Local organization
Bat committed
257 258 259 260 261 262

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.