diff options
| -rw-r--r-- | docs.md | 47 | ||||
| -rw-r--r-- | fpm/src/fpm/toml.f90 | 5 | ||||
| -rw-r--r-- | fpm/src/fpm_command_line.f90 | 24 |
3 files changed, 74 insertions, 2 deletions
@@ -24,9 +24,56 @@ sort: permission-alpha favicon: doc/media/favicon.ico print_creation_date: true extra_mods: iso_fortran_env:https://gcc.gnu.org/onlinedocs/gfortran/ISO_005fFORTRAN_005fENV.html + tomlf:https://toml-f.github.io/toml-f + M_CLI2:https://github.com/urbanjost/M_CLI2 creation_date: %Y-%m-%d %H:%M %z md_extensions: markdown.extensions.toc markdown.extensions.smarty --- [TOC] + +# Fortran package manager developer documentation + +This is the main documentation of the Fortran package manager (*fpm*). +This document serves as developer documentation of *fpm* itself and contains general advice for developing in the *fpm* code base. + + +## The package manifest + +The central object describing an *fpm* project is the package manifest ``fpm.toml``. +The manifest is written in TOML, you can find the TOML specification at the official [TOML homepage](https://toml.io). + +The ``fpm.toml`` file targets project developers and maintainers to relieve them from writing build files for their packages. +With the package manifest a central place to collect information about the project is provided. +It contains the versioning and licensing meta data, as well as the information on external dependencies and the required build-tools or compiler settings. + +The manifest format specific to *fpm* projects is documented in the [manifest reference](page/Manifest.html). + +@Note For a more practical but less complete guide on creating *fpm* projects see the [packaging guide](page/Packaging.html). + +The details of the TOML parsing are implemented with using the [tomlf](https://toml-f.github.io/toml-f) module. +Generally, the interface to all TOML related functions for *fpm* is found in the proxy module [[fpm_toml]]. + +All the manifest types are bundled in [[fpm_manifest]]. +While the specific subtables for the package configuration are found in the ``src/fpm/manifest`` directory, they should be reexported in the [[fpm_manifest]] module if they should be elsewhere in *fpm*. + + +## Command line interface + +*fpm* is mainly used as a command line tool. +To work with an *fpm* project as a user you can completely rely on the command line. + +The command line interface is build with the [M_CLI2](https://github.com/urbanjost/M_CLI2) module and can be found in [[fpm_command_line]]. + + +## Generating this documentation + +This documentation is generated by [FORD](https://github.com/Fortran-FOSS-Programmers/FORD). +For more details on the [project file](https://github.com/fortran-lang/fpm/docs.md) and the comment markup in the source code visit the [FORD documentation](https://github.com/Fortran-FOSS-Programmers/ford/wiki). + +To regenerate this documentation run: + +```shell +ford docs.md +``` diff --git a/fpm/src/fpm/toml.f90 b/fpm/src/fpm/toml.f90 index 34f7c58..2e1d6d3 100644 --- a/fpm/src/fpm/toml.f90 +++ b/fpm/src/fpm/toml.f90 @@ -1,4 +1,4 @@ -!> Interface to TOML processing library. +!># Interface to TOML processing library !> !> This module acts as a proxy to the `toml-f` public Fortran API and allows !> to selectively expose components from the library to `fpm`. @@ -10,7 +10,8 @@ !> This module allows to implement features necessary for `fpm`, which are !> not yet available in upstream `toml-f`. !> -!> For more details on the library used see: https://toml-f.github.io/toml-f +!> For more details on the library used see the +!> [TOML-Fortran](https://toml-f.github.io/toml-f) developer pages. module fpm_toml use fpm_error, only : error_t, fatal_error, file_not_found_error use fpm_strings, only : string_t diff --git a/fpm/src/fpm_command_line.f90 b/fpm/src/fpm_command_line.f90 index 2a44a4f..640adad 100644 --- a/fpm/src/fpm_command_line.f90 +++ b/fpm/src/fpm_command_line.f90 @@ -1,3 +1,27 @@ +!># Definition of the command line interface +!> +!> This module uses [M_CLI2](https://github.com/urbanjost/M_CLI2) to define +!> the command line interface. +!> To define a command line interface create a new command settings type +!> from the [[fpm_cmd_settings]] base class or the respective parent command +!> settings. +!> +!> The subcommand is selected by the first non-option argument in the command +!> line. In the subcase block the actual command line is defined and transferred +!> to an instance of the [[fpm_cmd_settings]], the actual type is used by the +!> *fpm* main program to determine which command entry point is chosen. +!> +!> To add a new subcommand add a new case to select construct and specify the +!> wanted command line and the expected default values. +!> Some of the following points also apply if you add a new option or argument +!> to an existing *fpm* subcommand. +!> Add this point you should create a help page for the new command in a simple +!> catman-like format as well in the ``set_help`` procedure. +!> Make sure to register new subcommands in the ``fpm-manual`` command by adding +!> them to the manual character array and in the help/manual case as well. +!> You should add the new command to the synopsis section of the ``fpm-list``, +!> ``fpm-help`` and ``fpm --list`` help pages below to make sure the help output +!> is complete and consistent as well. module fpm_command_line use fpm_environment, only : get_os_type, get_env, & OS_UNKNOWN, OS_LINUX, OS_MACOS, OS_WINDOWS, & |