diff options
Diffstat (limited to 'PACKAGING.md')
| -rw-r--r-- | PACKAGING.md | 456 |
1 files changed, 456 insertions, 0 deletions
diff --git a/PACKAGING.md b/PACKAGING.md new file mode 100644 index 0000000..28043c1 --- /dev/null +++ b/PACKAGING.md @@ -0,0 +1,456 @@ +# Preparing your package for FPM + +This document describes how you need to organize your application or library +for it to successfully build with the Fortran Package Manager (FPM). + +* [What kind of package can FPM build?](#what-kind-of-package-can-fpm-build) +* [Example package layouts](#example-package-layouts) + - [Single program](#single-program) + - [Single-module library](#single-module-library) + - [Multi-module library](#multi-module-library) + - [Application and library](#application-and-library) + - [Multi-level library](#multi-level-library) + +## What kind of package can FPM build? + +You can use FPM to build: + +* Applications (program only) +* Libraries (modules only) +* Combination of the two (programs and modules combined) + +Let's look at some examples of different kinds of package layouts that you can +use with FPM. + +## Example package layouts + +This section describes some example package layouts that you can build with FPM. +You can use them to model the layout of your own package. + +### Single program + +Let's start with the simplest package imaginable--a single program without +dependencies or modules. +Here's what the layout of the top-level directory looks like: + +``` +. +├── app +│ └── main.f90 +└── fpm.toml +``` + +We have one source file (`main.f90`) in one directory (`app`). +Its contents are: + +```fortran +program hello + print *, 'Hello, World!' +end program hello +``` + +This program prints the usual greeting to the standard output, and nothing more. + + +There's another important file in the top-level directory, `fpm.toml`. +This is FPM's configuration file specific to your package. +It includes all the data that FPM needs to build your app. +In our simple case, it looks like this: + +```toml +name = "hello" +version = "0.1.0" +license = "MIT" +author = "Jane Programmer" +maintainer = "jane@example.com" +copyright = "2020 Jane Programmer" +dependencies = [] +compiler = "gfortran" +``` + +The preamble includes some metadata, such as `license`, `author`, and similar, +that you may have seen in other package manager configuration files. +The one option that matters here right now is: + +```toml +name = "hello" +``` + +This line specifies the name of your package, which determines the name of +the executable file of your program. +In this example, our program executable, once built, will be called `hello`. + +Let's now build this program using FPM: + +``` +$ fpm build +# gfortran (for build/debug/app/main.o) +# gfortran (for build/debug/app/hello) +``` + +On the first line, we ran `fpm build` to compile and link the application. +The latter two lines are emitted by FPM, and indicate which command was +executed at each build step (`gfortran`), and which files have been output +by it: object file `main.o`, and executable `hello`. + +We can now run the app with `fpm run`: + +``` +$ fpm run + Hello, World! +``` + +> **Issue candidate**: fpm.toml setting `main = "main.f90"` is currently hardcoded. + +> **Question**: How to specify multiple executable programs? + +If your application needs to use a module internally, but you don't intent +to build it as a library to be used in other projects, you can include the +module in your program source file as well. +For example: + +```fortran +$ cat app/main.f90 +module math_constants + real, parameter :: pi = 4 * atan(1.) +end module math_constants + + +program hello + use math_constants, only: pi + print *, 'Hello, World!' + print *, 'pi = ', pi +end program hello +``` + +Now run this using `fpm run`: + +``` +$ fpm run +# gfortran (for build/debug/app/main.o) +# gfortran (for build/debug/app/hello) + Hello, World! + pi = 3.14159274 +``` + +Notice that you can run `fpm run`, and if the package hasn't been built yet, +`fpm build` will run automatically for you. +This is true if the source files have been updated since the last build. +Thus, if you want to run your application, you can skip the `fpm build` step, +and go straight to `fpm run`. + +Although we have named our program `hello`, which is the same name as the +package name in `fpm.toml`, you can name it anything you want as long as it's +permitted by the language. + +In this last example, our source file defined a `math_constants` module +inside the same source file as the main program. +Let's see how we can define an FPM package that makes this module available +as a library. + +### Single-module library + +The package layout for this example looks like this: + +``` +. +├── fpm.toml +└── src + └── math_constants.f90 +``` + +In this example we'll build a simple math constants library that exports +the number pi as a parameter: + +```fortran +$ cat src/math_constants.f90 +module math_constants + real, parameter :: pi = 4 * atan(1.) +end module math_constants +``` + +and our `fpm.toml` is the same as before. + +Now use `fpm build` to build the package: + +``` +$ fpm build +# gfortran (for build/debug/library/math_constants.o build/debug/library/math_constants.mod) +# ar (for build/debug/library/math_constants.a) +ar: creating build/debug/library/math_constants.a +``` + +Based on the output of `fpm build`, FPM first ran `gfortran` to emit the +binary object (`math_constants.o`) and module (`math_constants.mod`) files. +Then it ran `ar` to create a static library archive `math_constants.a`. +`build/debug/library` is thus both your include and library path, should you +want to compile and link an exteranl program with this library. + +For modules in the top-level (`src`) directory, FPM requires that: + +* The module has the same name as the source file. +* There is only one module per file. + +These two requirements simplify the build process for FPM. +As Fortran compilers emit module files (`.mod`) with the same name as the +module itself (but not the source file, `.f90`), naming the module the same as +the source file allows FPM to: + +* Uniquely and exactly map a source file (`.f90`) to its object (`.o`) and +module (`.mod`) files. +* Avoid conflicts with modules of the same name that could appear in dependency +packages (more on this in a bit). + +Since this is a library without executable programs, `fpm run` here does +nothing. + +> **Issue candidate**: `fpm run` should trigger an error if run in a project +> without executable programs. For example: +> +> ``` +> fpm error: This package has no executable programs. +> ``` + +In this example, our library is made of only one module. +However, most real-world libraries are likely to use multiple modules. +Let's see how you can package your multi-module library. + +### Multi-module library + +In this example, we'll use another module to define a 64-bit real kind +parameter and make it available in `math_constants` to define `pi` with +higher precision. +To make this exercise worthwhile, we'll define another math constant, +Euler's number. + +Our package layout looks like this: + +``` +. +├── fpm.toml +└── src + ├── math_constants.f90 + └── type_kinds.f90 +``` + +and our source file contents are: + +```fortran +$ cat src/math_constants.f90 +module math_constants + use type_kinds, only: rk + real(rk), parameter :: pi = 4 * atan(1._rk) + real(rk), parameter :: e = exp(1._rk) +end module math_constants + +$ cat src/type_kinds.f90 +module type_kinds + use iso_fortran_env, only: real64 + integer, parameter :: rk = real64 +end module type_kinds +``` + +and there are no changes to our `fpm.toml` relative to previous examples. + +Like before, notice that the module `type_kinds` is name exactly as the +source file that contains it. +This is important. + +By now you know how to build the package: + +``` +$ fpm build +# gfortran (for build/debug/library/type_kinds.o build/debug/library/type_kinds.mod) +# gfortran (for build/debug/library/math_constants.o build/debug/library/math_constants.mod) +# ar (for build/debug/library/math_constants.a) +ar: creating build/debug/library/math_constants.a +``` + +Our build path now contains: + +``` +$ ls build/debug/library/ +math_constants.a math_constants.mod math_constants.o type_kinds.mod type_kinds.o +``` + +and the static library includes all the object files: + +``` +$ nm build/debug/library/math_constants.a + +math_constants.o: + +type_kinds.o: +``` + +The takeaways from this example are that: + +* FPM automatically scanned the `src` directory for any source files. +* It also resolved the dependency order between different modules. + +### Application and library + +Let's now combine the two previous examples into one: +We'll build the math constants library _and_ an executable program that uses +it. +We'll use this program as a demo, and to verify that defining higher-precision +constants from the previous example actually worked. + +Here's the package layout for your application + library package: + +``` +. +├── app +│ └── main.f90 +├── fpm.toml +└── src + ├── math_constants.f90 + └── type_kinds.f90 +``` + +Our `fpm.toml` remains unchanged and our executable program source file is: + +```fortran +$ cat app/main.f90 +program demo + use math_constants, only: e, pi + print *, 'math_constants library demo' + print *, 'pi = ', pi + print *, 'e = ', e +end program demo +``` + +Let's go straight to running the demo program: + +``` +$ fpm run +# gfortran (for build/debug/library/type_kinds.o build/debug/library/type_kinds.mod) +# gfortran (for build/debug/library/math_constants.o build/debug/library/math_constants.mod) +# ar (for build/debug/library/math_constants.a) +ar: creating build/debug/library/math_constants.a +# gfortran (for build/debug/app/main.o) +# gfortran (for build/debug/app/math_constants) + math_constants library demo + pi = 3.1415926535897931 + e = 2.7182818284590451 +``` + +The FPM build + run process works as expected, and our program correctly outputs +higher-precision constants. + +So far we covered how FPM builds: + +* A single program +* A single-module library +* A multi-module library +* A program and a library + +However, all our modules so far have been organized in the top level source +directory. +More complex libraries may organize their modules in subdirectories. +Let's see how we can build this with FPM. + +### Multi-level library + +In this example, we'll define our library as a collection of modules, +two of which are defined in a subdirectory: + +``` +. +├── app +│ └── main.f90 +├── fpm.toml +└── src + ├── math_constants + │ ├── derived.f90 + │ └── fundamental.f90 + ├── math_constants.f90 + └── type_kinds.f90 +``` + +First, `fpm.toml` and `src/type_kinds.f90` remain unchanged relative to the +previous example. + +The rest of the source files are: + +```fortran +$ cat src/math_constants.f90 +module math_constants + use math_constants_fundamental, only: e, pi + use math_constants_derived, only: half_pi, two_pi +end module math_constants + +$ cat src/math_constants/fundamental.f90 +module math_constants_fundamental + use type_kinds, only: rk + real(rk), parameter :: pi = 4 * atan(1._rk) + real(rk), parameter :: e = exp(1._rk) +end module math_constants_fundamental + +$ cat src/math_constants/derived.f90 +module math_constants_derived + use math_constants_fundamental, only: pi + use type_kinds, only: rk + real(rk), parameter :: two_pi = 2 * pi + real(rk), parameter :: half_pi = pi / 2 +end module math_constants_derived + +$ cat app/main.f90 +program demo + use math_constants, only: e, pi, half_pi, two_pi + print *, 'math_constants library demo' + print *, 'pi = ', pi + print *, '2*pi = ', two_pi + print *, 'pi/2 = ', half_pi + print *, 'e = ', e +end program demo +``` + +Our top-level `math_constants` module now doesn't define the constants, +but imports them from the two modules in the subdirectory. +Constants `e` and `pi` we define in the `math_constants_fundamental` module, +and `two_pi` and `half_pi` in the `math_constants_derived` module. +From the main program, we access all the constants from the top-level +module `math_constants`. + +Let's build and run this package: + +``` +$ fpm run +# gfortran (for build/debug/library/type_kinds.o build/debug/library/type_kinds.mod) +# gfortran (for build/debug/library/math_constants_fundamental.o build/debug/library/math_constants_fundamental.mod) +# gfortran (for build/debug/library/math_constants_derived.o build/debug/library/math_constants_derived.mod) +# gfortran (for build/debug/library/math_constants.o build/debug/library/math_constants.mod) +# ar (for build/debug/library/math_constants.a) +ar: creating build/debug/library/math_constants.a +# gfortran (for build/debug/app/main.o) +# gfortran (for build/debug/app/math_constants) + math_constants library demo + pi = 3.1415926535897931 + 2*pi = 6.2831853071795862 + pi/2 = 1.5707963267948966 + e = 2.7182818284590451 +``` + +Again, FPM built and run the package as expected. + +Recall from an earlier example that FPM required the modules in the top-level +`src` directory to be named the same as their source file. +This is why `src/math_constants.f90` defines `module math_constants`. + +For modules defined in subdirectories, there's an additional requirement: +module name must contain the path components of the directory that its +source file is in. +In our case, `src/math_constants/fundamental.f90` defines +the `math_constants_fundamental` module. +Likewise, `src/math_constants/derived.f90` defines +the `math_constants_derived` module. + +This rule applies generally to any number of nested directories and modules. +For example, `src/a/b/c/d.f90` must define a module called `a_b_c_d`. + +Takeaways from this example are that: + +* You can place your module source files in any levels of subdirectories inside `src`. +* The module name must include the path components and the source file name--for example, +`src/a/b/c/d.f90` must define a module called `a_b_c_d`. |