aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSebastian Ehlert <28669218+awvwgk@users.noreply.github.com>2020-12-06 23:51:57 +0100
committerSebastian Ehlert <28669218+awvwgk@users.noreply.github.com>2020-12-07 00:08:42 +0100
commitf17591bc8f0c1783ea86db080b0260dbefb7b588 (patch)
treec4604e12b0506757473b43cf2b4c9e477e331aac
parente9a012ae43812f516616674bc06c366bee1b779f (diff)
downloadfpm-f17591bc8f0c1783ea86db080b0260dbefb7b588.tar.gz
fpm-f17591bc8f0c1783ea86db080b0260dbefb7b588.zip
Update developer documentation (manifest + command line)
- populate the landing page at https://fpm.fortran-lang.org - link with the TOML homepage and describe the package manifest format - sketch the implementation of the TOML parsing and link to TOML-Fortran - describe the scope of *fpm* with respect to the package manifest - link with the M_CLI2 repository and describe the command line interface - add a short documentation on the usage of M_CLI2 for the command line - describe the process of adding new subcommands and arguments - outline the generation of the developer pages and link to the FORD wiki
-rw-r--r--docs.md47
-rw-r--r--fpm/src/fpm/toml.f905
-rw-r--r--fpm/src/fpm_command_line.f9024
3 files changed, 74 insertions, 2 deletions
diff --git a/docs.md b/docs.md
index 800cfab..1b4aef1 100644
--- a/docs.md
+++ b/docs.md
@@ -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 03daf6f..67c682a 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, &
OS_UNKNOWN, OS_LINUX, OS_MACOS, OS_WINDOWS, &