diff options
| -rw-r--r-- | README.md | 3 | ||||
| -rw-r--r-- | bootstrap/src/Build.hs | 1 | ||||
| -rwxr-xr-x | install.sh | 4 | ||||
| -rw-r--r-- | manifest-reference.md | 361 |
4 files changed, 366 insertions, 3 deletions
@@ -81,4 +81,5 @@ to run, as can `fpm test`; like `fpm run specific_executable`. Command line arguments can also be passed to the executable(s) or test(s) with the option `--args "some arguments"`. -See additional instructions in the [Packaging guide](PACKAGING.md). +See additional instructions in the [Packaging guide](PACKAGING.md) or +the [manifest reference](manifest-reference.md). diff --git a/bootstrap/src/Build.hs b/bootstrap/src/Build.hs index 083e646..3f647cd 100644 --- a/bootstrap/src/Build.hs +++ b/bootstrap/src/Build.hs @@ -105,6 +105,7 @@ buildProgram programDirectory' libraryDirectories sourceExtensions buildDirector want [buildDirectory </> programName <.> exe] buildDirectory </> programName <.> exe %> \executable -> do need objectFiles + need archives cmd compiler objectFiles archives ["-o", executable] flags mapM_ infoToRule compileTimeInfo @@ -19,14 +19,14 @@ else fi fi -if [[ -x "$install_path/fpm" ]]; then +if [ -x "$install_path/fpm" ]; then echo "Overwriting existing fpm installation in $install_path" fi cd bootstrap stack install -if [[ -x "$install_path/fpm" ]]; then +if [ -x "$install_path/fpm" ]; then echo "fpm installed successfully to $install_path" else echo "fpm installation unsuccessful: fpm not found in $install_path" diff --git a/manifest-reference.md b/manifest-reference.md new file mode 100644 index 0000000..5dd038d --- /dev/null +++ b/manifest-reference.md @@ -0,0 +1,361 @@ +# 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-executables*](#automatic-target-discovery): + Toggle automatic discovery of executables +- 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 decription 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 modifed 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 executeted 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 + +*Example:* + +```toml +[[executable]] +name = "app-name" +source-dir = "prog" +main = "program.f90" + +[[executable]] +name = "app-tool" +[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" }, +] +``` + + +### 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 + +*Example:* + +```toml +[[test]] +name = "test-name" +source-dir = "testing" +main = "tester.F90" + +[[test]] +name = "tester" +[test.dependencies] +helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git" } +``` + + +## 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`` and ``test`` directories for ``program`` definitions and declares them as executable and test targets, respectively. +The automatic discovery is enabled by default. + +To disable the automatic discovery of targets set the *auto-executables* and *auto-tests* entry to *false*. + +```toml +[build] +auto-executables = 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. |