1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
|
# Fortran package manager (fpm) manifest reference
The ``fpm.toml`` file for each project is called its *manifest*.
It is written using the [TOML] format.
Every manifest file consists of the following sections:
- [*name*](#project-name):
The name of the project
- [*version*](#project-version):
The version of the project
- [*license*](#project-license):
The project license
- [*maintainer*](#project-maintainer):
Maintainer of the project
- [*author*](#project-author):
Author of the project
- [*copyright*](#project-copyright):
Copyright of the project
- [*description*](#project-description):
Description of the project
- [*categories*](#project-categories):
Categories associated with the project
- [*keywords*](#project-keywords):
Keywords describing the project
- [*homepage*](#project-homepage):
The project's homepage
- Build configuration:
- [*auto-tests*](#automatic-target-discovery):
Toggle automatic discovery of test executables
- [*auto-examples*](#automatic-target-discovery):
Toggle automatic discovery of example programs
- [*auto-executables*](#automatic-target-discovery):
Toggle automatic discovery of executables
- [*link*](#link-external-libraries):
Link with external dependencies
- Target sections:
- [*library*](#library-configuration)
Configuration of the library target
- [*executable*](#executable-targets)
Configuration of the executable targets
- [*test*](#test-targets)
Configuration of the test targets
- Dependency sections:
- [*dependencies*](#specifying-dependencies):
Project library dependencies
- [*dev-dependencies*](#development-dependencies):
Dependencies only needed for tests
[TOML]: https://toml.io/
## Project name
The project name identifies the package and is used to refer to it.
It is used when listing the project as dependency for another package and the default name of the library and executable target.
Therefore, the project name must always be present.
*Example:*
```toml
name = "hello_world"
```
## Project version
The version number of the project is specified as string.
A standardized way to manage and specify versions is the [Semantic Versioning] scheme.
*Example:*
```toml
version = "1.0.0"
```
[Semantic Versioning]: https://semver.org
## Project license
The project license field contains the license identifier.
A standardized way to specify licensing information are [SPDX] identifiers.
*Examples:*
Projects licensed under the [GNU Lesser General Public License](https://www.gnu.org/licenses/lgpl-3.0-standalone.html), either version 3 or any later version, is specified as
```toml
license = "LGPL-3.0-or-later"
```
Dual licensed project under the [Apache license, version 2.0](http://www.apache.org/licenses/LICENSE-2.0) or the [MIT license](https://opensource.org/licenses/MIT) are specified as
```toml
license = "Apache-2.0 OR MIT"
```
[SPDX]: https://spdx.org/licenses/
## Project maintainer
Information on the project maintainer and means to reach out to them.
*Example:*
```toml
maintainer = "jane.doe@example.com"
```
## Project author
Information on the project author.
*Example:*
```toml
author = "Jane Doe"
```
## Project copyright
A statement clarifying the copyright status of the project.
*Example:*
```toml
copyright = "Copyright 2020 Jane Doe"
```
## Project description
The description provides a short summary on the project.
It should be plain text and not using any markup formatting.
*Example:*
```toml
description = "A short summary on this project"
```
## Project categories
The project can be associated with different categories.
*Example:*
```toml
categories = ["io"]
```
## Project keywords
The keywords field is an array of strings describing the project.
*Example:*
```toml
keywords = ["hdf5", "mpi"]
```
## Project homepage
URL to the webpage of the project.
*Example:*
```toml
homepage = "https://stdlib.fortran-lang.org"
```
## Project targets
Every fpm project can define library, executable and test targets.
Library targets are exported and useable for other projects.
### Library configuration
Defines the exported library target of the project.
A library is generated if the source directory is found in a project.
The default source directory is ``src`` but can be modified in the *library* section using the *source-dir* entry.
Paths for the source directory are given relative to the project root and use ``/`` as path separator on all platforms.
*Example:*
```toml
[library]
source-dir = "lib"
```
#### Custom build script
> Supported in Bootstrap fpm only
Projects with custom build scripts can specify those in the *build-script* entry.
The custom build script will be executed when the library build step is reached.
*Example:*
```toml
[library]
build-script = "build.sh"
```
Build scripts written in ``make`` are automatically detected and executed with ``make``
```toml
[library]
build-script = "Makefile"
```
### Executable targets
Executable targets are Fortran programs defined as *executable* sections.
If no executable section is specified the ``app`` directory is searched for program definitions.
For explicitly specified executables the *name* entry must always be specified.
The source directory for each executable can be adjusted in the *source-dir* entry.
Paths for the source directory are given relative to the project root and use ``/`` as path separator on all platforms.
The source file containing the program body can be specified in the *main* entry.
Executables can have their own dependencies.
See [specifying dependencies](#specifying-dependencies) for more details.
> Dependencies supported in Bootstrap fpm only
Executables can also specify their own external library dependencies.
See [external libraries](#link-external-libraries) for more details.
> Linking against libraries is supported in Fortran fpm only
*Example:*
```toml
[[ executable ]]
name = "app-name"
source-dir = "prog"
main = "program.f90"
[[ executable ]]
name = "app-tool"
link = "z"
[executable.dependencies]
helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git" }
```
Specifying many separate executables can be done by using inline tables for brevity instead
```toml
executable = [
{ name = "a-prog" },
{ name = "app-tool", source-dir = "tool" },
]
```
### Example targets
Example applications for a project are defined as *example* sections.
If no example section is specified the ``example`` directory is searched for program definitions.
For explicitly specified examples the *name* entry must always be specified.
The source directory for each example can be adjusted in the *source-dir* entry.
Paths for the source directory are given relative to the project root and use ``/`` as path separator on all platforms.
The source file containing the program body can be specified in the *main* entry.
Examples can have their own dependencies.
See [specifying dependencies](#specifying-dependencies) for more details.
> Dependencies supported in Bootstrap fpm only
Examples can also specify their own external library dependencies.
See [external libraries](#link-external-libraries) for more details.
> Linking against libraries is supported in Fortran fpm only
*Example:*
```toml
[[ example ]]
name = "demo-app"
source-dir = "demo"
main = "program.f90"
[[ example ]]
name = "example-tool"
link = "z"
[example.dependencies]
helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git" }
```
### Test targets
Test targets are Fortran programs defined as *test* sections.
They follow similar rules as the executable targets.
If no test section is specified the ``test`` directory is searched for program definitions.
For explicitly specified tests the *name* entry must always be specified.
The source directory for each test can be adjusted in the *source-dir* entry.
Paths for the source directory are given relative to the project root and use ``/`` as path separator on all platforms.
The source file containing the program body can be specified in the *main* entry.
Tests can have their own dependencies.
See [specifying dependencies](#specifying-dependencies) for more details.
> Dependencies supported in Bootstrap fpm only
Tests can also specify their own external library dependencies.
See [external libraries](#link-external-libraries) for more details.
> Linking against libraries is supported in Fortran fpm only
*Example:*
```toml
[[ test ]]
name = "test-name"
source-dir = "testing"
main = "tester.F90"
[[ test ]]
name = "tester"
link = ["blas", "lapack"]
[test.dependencies]
helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git" }
```
## Link external libraries
> Supported in Fortran fpm only
To declare link time dependencies on external libraries a list of native libraries can be specified in the *link* entry.
Specify either one library as string or a list of strings in case several libraries should be linked.
When possible the project should only link one native library.
The list of library dependencies is exported to dependent packages.
*Example:*
To link against the zlib compression library use
```toml
[build]
link = "z"
```
To dependent on LAPACK also BLAS should be linked.
In this case the order of the libraries matters:
```toml
[build]
link = ["blas", "lapack"]
```
## Automatic target discovery
> Supported in Fortran fpm only
Executables and test can be discovered automatically in their default directories.
The automatic discovery recursively searches the ``app``, ``example``, and ``test`` directories for ``program`` definitions and declares them as executable, example, and test targets, respectively.
The automatic discovery is enabled by default.
To disable the automatic discovery of targets set the *auto-executables*, *auto-examples*, and *auto-tests* entry to *false*.
```toml
[build]
auto-executables = false
auto-examples = false
auto-tests = false
```
## Specifying dependencies
Dependencies can be declared in the *dependencies* table in the manifest root or the [*executable*](#executable-targets) or [*test*](#test-targets) sections.
When declared in the manifest root the dependencies are exported with the project.
### Local dependencies
To declare local dependencies use the *path* entry.
```toml
[dependencies]
my-utils = { path = "utils" }
```
Local dependency paths are given relative to the project root and use ``/`` as path separator on all platforms.
### Dependencies from version control systems
Dependencies can be specified by the projects git repository.
```toml
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f" }
```
To use a specific upstream branch declare the *branch* name with
```toml
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", branch = "master" }
```
Alternatively, reference tags by using the *tag* entry
```toml
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", tag = "v0.2.1" }
```
To pin a specific revision specify the commit hash in the *rev* entry
```toml
[dependencies]
toml-f = { git = "https://github.com/toml-f/toml-f", rev = "2f5eaba" }
```
For more verbose layout use normal tables rather than inline tables to specify dependencies
```toml
[dependencies]
[dependencies.toml-f]
git = "https://github.com/toml-f/toml-f"
rev = "2f5eaba864ff630ba0c3791126a3f811b6e437f3"
```
### Development dependencies
Development dependencies allow to declare *dev-dependencies* in the manifest root, which are available to all tests but not exported with the project.
|