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

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

Bat's avatar
Bat committed
5
## poulp.toml
Bat's avatar
Bat committed
6

Bat's avatar
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's avatar
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's avatar
Bat committed
15
16
17
```toml
name = "my-project" # correct
name = "my-project-123" # correct
Bat's avatar
Bat committed
18

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

Bat's avatar
Bat committed
23
*This key is mandatory.*
Bat's avatar
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's avatar
Bat committed
29
*This key is mandatory.*
Bat's avatar
Bat committed
30
31
32
33
34

### description

This is just a short description of your package.

Bat's avatar
Bat committed
35
36
### keywords

Bat's avatar
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's avatar
Bat committed
38
39
40
41
42
43
44

### homepage

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

### bugs

Bat's avatar
Bat committed
45
Specifies where to report bugs. It is an table, which can contain this fields.
Bat's avatar
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's avatar
Bat committed
52
The name of the license of your project, or the path to the file containing its license.
Bat's avatar
Bat committed
53

Bat's avatar
Bat committed
54
### authors
Bat's avatar
Bat committed
55

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

### files

The files to include at compilation.

### repository

Bat's avatar
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's avatar
Bat committed
65

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

The path to a directory containing personal VAPIs.

### output

Bat's avatar
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's avatar
Bat committed
73

Bat's avatar
Bat committed
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's avatar
Bat committed
78
79
### scripts

Bat's avatar
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's avatar
Bat committed
81

Bat's avatar
Bat committed
82
### dependencies
Bat's avatar
Bat committed
83

Bat's avatar
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's avatar
Bat committed
85

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

Bat's avatar
Bat committed
88
### dev-dependencies
Bat's avatar
Bat committed
89

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

Bat's avatar
Bat committed
92
### vala-version
Bat's avatar
Bat committed
93

Bat's avatar
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's avatar
Bat committed
118
119

### compiler-params
Bat's avatar
Bat committed
120
121
122

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

Bat's avatar
Bat committed
123
124
125



Bat's avatar
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's avatar
Bat committed
132
### search package
Bat's avatar
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's avatar
Bat committed
141
### info package
Bat's avatar
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's avatar
Bat committed
164
### publish major|minor|patch --repo url [--no-changelog]
Bat's avatar
Bat committed
165

Bat's avatar
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's avatar
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's avatar
Bat committed
171
172
**Warning** `--repo` and `--no-changelog` are not implemented yet.

Bat's avatar
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's avatar
Bat committed
193
194
It clones the libraries, checkout to the most recent matching version, builds it and installs the result.

Bat's avatar
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's avatar
Bat committed
216
217
# Variables

Bat's avatar
Bat committed
218
poulp defines some environment varaibles when spawning a command. You can use them in `output`, `compiler-params` and your scripts.
Bat's avatar
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's avatar
Bat committed
227
228
# Remote repositories organization

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

Bat's avatar
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's avatar
Bat committed
232

Bat's avatar
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's avatar
Bat committed
234

Bat's avatar
Bat committed
235
*Example `packages.json` file*
Bat's avatar
Bat committed
236

Bat's avatar
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's avatar
Bat committed
246
247
```

Bat's avatar
Bat committed
248
It is planed to make it possible for package to install templates, but not available yet.
Bat's avatar
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's avatar
Bat committed
253
254
255



Bat's avatar
Bat committed
256
# Local organization
Bat's avatar
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.