diff options
| -rw-r--r-- | CONTRIBUTING.md | 70 | ||||
| -rw-r--r-- | PACKAGING.md | 351 | ||||
| -rw-r--r-- | README.md | 72 |
3 files changed, 244 insertions, 249 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1332278..9a1f5a3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,14 +1,13 @@ # Contributing to the Fortran Package Manager -Thank you for considering contributing to the Fortran Package Manager (fpm). +Thank you for considering contributing to the Fortran Package Manager (*fpm*). Please review and follow these guidelines to make the contribution process -simple and effective for all involved. -It will help communicate that you respect the time of the community -developers. -In return, the community will help address your problem, evaluate changes, and -guide you through your pull requests. +simple and effective for all involved. It will help communicate that you +respect the time of the community developers. In return, the community will +help address your problem, evaluate changes, and guide you through your pull +requests. -By contributing to fpm, you certify that you own or are allowed to share the +By contributing to *fpm*, you certify that you own or are allowed to share the content of your contribution under the [fpm license](https://github.com/fortran-lang/fpm/blob/master/LICENSE). @@ -28,13 +27,13 @@ This allows us to focus on substance rather than style. ## Reporting a bug -A bug is a _demonstrable problem_ caused by the code in this repository. +A bug is a *demonstrable problem* caused by the code in this repository. Good bug reports are extremely valuable to us—thank you! Before opening a bug report: -1. Check if the issue has already been reported. - ([issues](https://github.com/fortran-lang/fpm/issues)) +1. Check if the issue has already been reported + ([issues](https://github.com/fortran-lang/fpm/issues)). 2. Check if it is still an issue or it has been fixed? Try to reproduce it with the latest version from the master branch. 3. Isolate the problem and create a minimal test case. @@ -42,7 +41,7 @@ Before opening a bug report: A good bug report should include all information needed to reproduce the bug. Please be as detailed as possible: -1. Which version of fpm are you using? Please be specific. +1. Which version of *fpm* are you using? Please be specific. 2. What are the steps to reproduce the issue? 3. What is the expected outcome? 4. What happens instead? @@ -52,21 +51,18 @@ minimal back-and-forth. ## Suggesting a feature -Before suggesting a new feature, take a moment to find out if it fits -the scope of the project, or if it has already been discussed. -It is up to you to provide a strong argument to convince the community of the -benefits of this feature. -Please provide as much detail and context as possible. -If applicable, include a mocked-up snippet of what the output or behavior would -look like with this feature implemented. -"Crazy", out-of-the-box ideas are especially welcome. -It's quite possible that we are not considering an unusually creative solution. +Before suggesting a new feature, take a moment to find out if it fits the scope +of the project, or if it has already been discussed. It is up to you to provide +a strong argument to convince the community of the benefits of this feature. +Please provide as much detail and context as possible. If applicable, include a +mocked-up snippet of what the output or behavior would look like with this +feature implemented. “Crazy”, out-of-the-box ideas are especially welcome. +It’s quite possible that we are not considering an unusually creative solution. ## Workflow -fpm is a community project. -There is no one single person making final decisions. -This is the workflow that we follow: +*fpm* is a community project. There is no one single person making final +decisions. This is the workflow that we follow: 1. Open a [new issue](https://github.com/fortran-lang/fpm/issues/new) to describe a bug or propose a new feature. @@ -74,18 +70,19 @@ This is the workflow that we follow: request. 2. Discuss with the community and reach majority consensus about what should be done about the bug or feature request. - We define "majority" loosely as 80%. + We define “majority” loosely as 80%. This means that at least 4 of 5 people engaged in the discussion should be able to agree on the next step. This allows us to have the community mostly agree while not getting stuck if one person disagrees. At this stage, the scope of the fix/feature, its behavior, and API if applicable should be defined. - Only when you have community concensus on these items you should proceed - to writing code and opening a PR. - __When actively working on code towards a PR, please assign yourself to the issue on github.__ - This is good collaborative practice to avoid duplicated effort and also inform others what you - are currently working on. + Only when you have community concensus on these items you should proceed to + writing code and opening a PR. + **When actively working on code towards a PR, please assign yourself to the + issue on GitHub.** + This is good collaborative practice to avoid duplicated effort and also + inform others what you are currently working on. 3. Open a new Pull Request (PR) with your contribution. The body of the PR should at least include a bullet-point summary of the changes, and a detailed description is encouraged. @@ -96,17 +93,16 @@ This is the workflow that we follow: sufficient. For implementation of bigger features, request 3 to 4 or more reviewers. Ideally, request reviewers that participated in step 2. -5. If your PR implements a feature that adds or changes the behavior of fpm, +5. If your PR implements a feature that adds or changes the behavior of *fpm*, your PR must also include appropriate changes to the documentation. This workflow can evolve and change over time as we learn how best to work -together. -If you have an idea on how to improve the workflow itself, please open an issue -and we'll discuss it. +together. If you have an idea on how to improve the workflow itself, please +open an issue and we’ll discuss it. ## General guidelines -* A PR should implement _only one_ feature or bug fix. +* A PR should implement *only one* feature or bug fix. * Do not commit changes to files that are irrelevant to your feature or bug fix. * Smaller PRs are better than large PRs, and will lead to a shorter review and merge cycle @@ -115,12 +111,12 @@ and we'll discuss it. * Again, please follow the [Fortran stdlib style guide](https://github.com/fortran-lang/stdlib/blob/master/STYLE_GUIDE.md). -## For New Contributors +## For new contributors If you have never created a pull request before, welcome :tada:. You can learn how from [this great tutorial](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github). -Don't know where to start? +Don’t know where to start? You can start by looking through the list of -[open issues](https://github.com/fortran-lang/fpm/issues). +[open issues](https://github.com/fortran-lang/fpm/issues). diff --git a/PACKAGING.md b/PACKAGING.md index 941f1b0..f5f28e3 100644 --- a/PACKAGING.md +++ b/PACKAGING.md @@ -1,9 +1,9 @@ # 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). +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) +* [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) @@ -15,27 +15,27 @@ for it to successfully build with the Fortran Package Manager (FPM). - [Adding dependencies](#adding-dependencies) - [Custom build scripts](#custom-build-scripts) -## What kind of package can FPM build? +## What kind of package can fpm build? -You can use FPM to 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. +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. +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: +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: ``` . @@ -44,22 +44,20 @@ Here's what the layout of the top-level directory looks like: └── fpm.toml ``` -We have one source file (`main.f90`) in one directory (`app`). -Its contents are: +We have one source file (`main.f90`) in one directory (`app`). Its contents +are: ```fortran -program hello - print *, 'Hello, World!' -end program hello +program main + print *, 'Hello, World!' +end program main ``` 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: +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" @@ -71,18 +69,18 @@ copyright = "2020 Jane Programmer" ``` 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: +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`. +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: +Let’s now build this program using *fpm*: ``` $ fpm build @@ -91,7 +89,7 @@ $ fpm build ``` 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 +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`. @@ -102,7 +100,7 @@ $ fpm run Hello, World! ``` -If your application needs to use a module internally, but you don't intend +If your application needs to use a module internally, but you don’t intend 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: @@ -110,18 +108,17 @@ For example: ```fortran $ cat app/main.f90 module math_constants - real, parameter :: pi = 4 * atan(1.) + 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 +program main + use math_constants, only: pi + print *, 'Hello, World!' + print *, 'pi = ', pi +end program main ``` -Now run this using `fpm run`: +Now, run this using `fpm run`: ``` $ fpm run @@ -131,20 +128,18 @@ $ fpm run 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`. +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 +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. +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 @@ -157,13 +152,13 @@ The package layout for this example looks like this: └── math_constants.f90 ``` -In this example we'll build a simple math constants library that exports +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.) + real, parameter :: pi = 4 * atan(1.) end module math_constants ``` @@ -178,21 +173,21 @@ $ fpm build ar: creating build/debug/library/math_constants.a ``` -Based on the output of `fpm build`, FPM first ran `gfortran` to emit the +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: +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: +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. @@ -202,17 +197,16 @@ packages (more on this in a bit). Since this is a library without executable programs, `fpm run` here does nothing. -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. +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 +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. +higher precision. To make this exercise worthwhile, we’ll define another math +constant, Euler’s number. Our package layout looks like this: @@ -224,20 +218,20 @@ Our package layout looks like this: └── type_kinds.f90 ``` -and our source file contents are: +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) + 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 + use iso_fortran_env, only: real64 + integer, parameter :: rk = real64 end module type_kinds ``` @@ -264,7 +258,7 @@ $ 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: +And the static library includes all the object files: ``` $ nm build/debug/library/math_constants.a @@ -276,18 +270,17 @@ type_kinds.o: The takeaways from this example are that: -* FPM automatically scanned the `src` directory for any source files. +* *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. +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: +Here’s the package layout for your application + library package: ``` . @@ -303,15 +296,15 @@ 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 +program main + use math_constants, only: e, pi + print *, 'math_constants library demo' + print *, 'pi = ', pi + print *, 'e = ', e +end program main ``` -Let's go straight to running the demo program: +Let’s go straight to running the demo program: ``` $ fpm run @@ -326,10 +319,10 @@ ar: creating build/debug/library/math_constants.a e = 2.7182818284590451 ``` -The FPM build + run process works as expected, and our program correctly outputs -higher-precision constants. +The *fpm* build + run process works as expected, and our program correctly +outputs higher-precision constants. -So far we covered how FPM builds: +So far we covered how *fpm* builds: * A single program * A single-module library @@ -337,14 +330,13 @@ So far we covered how FPM builds: * 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. +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: +In this example, we’ll define our library as a collection of modules, two of +which are defined in a subdirectory: ``` . @@ -367,44 +359,43 @@ 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 + 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) + 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 + 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 +program main + 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 main ``` -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`. +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: +Let’s build and run this package: ``` $ fpm run @@ -423,19 +414,17 @@ ar: creating build/debug/library/math_constants.a e = 2.7182818284590451 ``` -Again, FPM built and run the package as expected. +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`. +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. +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`. @@ -448,12 +437,12 @@ Takeaways from this example are that: ### Be more explicit -So far we've let FPM use its defaults to determine the layout of our package. +So far we’ve let *fpm* use its defaults to determine the layout of our package. It determined where our library sources would live, what the name of the executable will be, and some other things. But we can be more explicit about it, and make some changes to those things. -Let's look at what the `fpm.toml` file from our last example would look like if +Let’s look at what the `fpm.toml` file from our last example would look like if we specified everything. ```toml @@ -474,17 +463,18 @@ main="main.f90" ``` You can see that by making these explicit in the `fpm.toml` we are able to -change many of the settings that FPM used by default. We can change the folders -where our sources are stored, we can change the name of our executable, and we -can change the name of the file our program is defined in. +change many of the settings that *fpm* used by default. We can change the +folders where our sources are stored, we can change the name of our executable, +and we can change the name of the file our program is defined in. ### Add some tests -FPM also provides support for unit testing. By default, FPM looks for a program -in `test/main.f90` which it will compile and execute with the command `fpm test`. -The tests are treated pretty much exactly like the executables. Let's define -one explicitly in our `fpm.toml` file. We'll make sure that our definition of -`pi` satisfies the property `sin(pi) == 0.0`. Here's the `fpm.toml` file, +*fpm* also provides support for unit testing. By default, *fpm* looks for a +program in `test/main.f90` which it will compile and execute with the command +`fpm test`. The tests are treated pretty much exactly like the executables. +Let’s define one explicitly in our `fpm.toml` file. We’ll make sure that our +definition of `pi` satisfies the property `sin(pi) == 0.0`. Here’s the +`fpm.toml` file: ```toml name = "math_constants" @@ -511,11 +501,10 @@ main="main.f90" where the contents of the `main.f90` file are ```fortran -program tests - use math_constants, only: pi - - print *, "sin(pi) = ", sin(pi) -end program tests +program main + use math_constants, only: pi + print *, "sin(pi) = ", sin(pi) +end program main ``` With this setup, we can run our tests. @@ -535,12 +524,12 @@ ar: creating build/debug/library/math_constants.a sin(pi) = 1.2246467991473532E-016 ``` -### Adding Dependencies +### Adding dependencies -Inevitably you'll want to be able to include other libraries in your project. +Inevitably, you’ll want to be able to include other libraries in your project. fpm makes this incredibly simple, by taking care of fetching and compiling your dependencies for you. You just tell it what your dependencies are, and where to -find them. Let's add a dependency to our library. Now our `fpm.toml` file looks +find them. Let’s add a dependency to our library. Now our `fpm.toml` file looks like this: ```toml @@ -572,19 +561,19 @@ Now you can use any modules from this library anywhere in your code. Just like this: ```fortran -program demo - use helloff, only: create_greeting - 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 - print *, create_greeting("fpm") -end program demo +program main + use helloff, only: create_greeting + 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 + print *, create_greeting("fpm") +end program main ``` -And now `fpm run` will output the following: +And now, `fpm run` will output the following: ``` math_constants library demo @@ -596,10 +585,10 @@ And now `fpm run` will output the following: ``` Additionally, any users of your library will now automatically depend on your -dependencies too. So if you don't need that depedency for the library, like in +dependencies too. So if you don’t need that depedency for the library, like in the above example, then you can specify it for the specific executable like below. Then fpm will still fetch and compile it when building your executable, -but users of your library won't have to. +but users of your library won’t have to. ```toml name = "math_constants" @@ -619,7 +608,6 @@ main="main.f90" [executable.dependencies] helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git" } - [[test]] name="runTests" source-dir="test" @@ -627,9 +615,9 @@ main="main.f90" ``` You can also specify dependencies for your tests in a similar way, with -`[test.dependencies]` instead of `[executable.dependencies]`. There's also +`[test.dependencies]` instead of `[executable.dependencies]`. There’s also another option for test dependencies. The below example makes the dependencies -available for all the tests, but again your users won't depend on these. +available for all the tests, but again your users won’t depend on these. ```toml name = "math_constants" @@ -656,20 +644,23 @@ source-dir="test" main="main.f90" ``` -You can also be specific about which version of a dependency you'd like. You can -specify a branch to use like `helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git", branch = "master" }`, -or a tag like `helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git", tag = "v1.2.3" }`, -or even a specific commit like `helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git", rev = "a1b2c3" }`. -You can even specify the path to another folder, if for example you've got another -fpm package in the same repository. Like this: `helloff = { path = "helloff" }`. -Note that you should *not* specify paths outside of your repository, or things -won't work for your users. +You can also be specific about which version of a dependency you’d like. You can +specify a branch to use like +`helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git", branch = "master" }`, +or a tag like +`helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git", tag = "v1.2.3" }`, +or even a specific commit like +`helloff = { git = "https://gitlab.com/everythingfunctional/helloff.git", rev = "a1b2c3" }`. +You can even specify the path to another folder, if for example you’ve got +another fpm package in the same repository. Like this: +`helloff = { path = "helloff" }`. Note that you should *not* specify paths +outside of your repository, or things won’t work for your users. -### Custom Build Scripts +### Custom build scripts If there is something special about your library that makes fpm unable to build -it, you can provide your own build script. fpm will then simply call your -build script to build the library. +it, you can provide your own build script. fpm will then simply call your build +script to build the library. To specify a build script to be used, put it in the library section of your `fpm.toml` file, like: @@ -680,15 +671,15 @@ source-dir="src" build-script="my_build_script" ``` -fpm will set the following environment variables to specify some parameters to -the build script. +*fpm* will set the following environment variables to specify some parameters to +the build script: -* `FC` - The Fortran compiler to be used -* `FFLAGS` - The flags that should be passed to the Fortran compiler -* `BUILD_DIR` - Where the compiled files should be placed -* `INCLUDE_DIRS` - The folders where any dependencies can be found, space seperated. - It is then the responsibility of the build script to generate the appropriate - include flags. +* `FC` – The Fortran compiler to be used. +* `FFLAGS` – The flags that should be passed to the Fortran compiler. +* `BUILD_DIR` – Where the compiled files should be placed. +* `INCLUDE_DIRS` – The folders where any dependencies can be found, space seperated. +It is then the responsibility of the build script to generate the appropriate +include flags. Additionally, script will be called with the name of the archive (`*.a` file) that should be produced as the command line argument. @@ -1,16 +1,16 @@ # Fortran Package Manager -This is the repository of the Fortran Package Manager (fpm). -If you are looking for _fpm--packaging made simple_ instead, see +This is the repository of the Fortran Package Manager (*fpm*). If you are +looking for *fpm – packaging made simple* instead, see [jordansissel/fpm](https://github.com/jordansissel/fpm). -Fortran Package Manager is an early prototype. -You can use it to build and package your Fortran projects, as -well as to include supported Fortran dependency projects. -As a prototype, changes to fpm's behavior and inputs may occur as development continues. -Please follow the [issues](https://github.com/fortran-lang/fpm/issues) -to contribute and/or stay up to date with the development. -As the prototype matures and we enter production, we will do our best to stay backwards compatible. +Fortran Package Manager is an early prototype. You can use it to build and +package your Fortran projects, as well as to include supported Fortran +dependency projects. As a prototype, changes to *fpm*’s behavior and inputs may +occur as development continues. Please follow the +[issues](https://github.com/fortran-lang/fpm/issues) to contribute and/or stay +up to date with the development. As the prototype matures and we enter +production, we will do our best to stay backwards compatible. To report a bug report or suggest a feature, please read our [contributor guidelines](CONTRIBUTING.md). @@ -19,54 +19,62 @@ To report a bug report or suggest a feature, please read our ### Install Haskell -To install **Haskell Stack**, follow these [instructions](https://docs.haskellstack.org/en/stable/install_and_upgrade/), -users without superuser (admin) permissions should follow the [manual installation](https://docs.haskellstack.org/en/stable/install_and_upgrade/#manual-download_2) procedure. +To install **Haskell Stack**, follow these +[instructions](https://docs.haskellstack.org/en/stable/install_and_upgrade/), +users without superuser (admin) permissions should follow the +[manual installation](https://docs.haskellstack.org/en/stable/install_and_upgrade/#manual-download_2) +procedure. ### Download this repository ```bash -git clone https://github.com/fortran-lang/fpm -cd fpm +$ git clone https://github.com/fortran-lang/fpm +$ cd fpm/ ``` -### Build and Test fpm +### Build and test fpm + +Bootstrap *fpm* using: -Bootstrap fpm using: ```bash -cd bootstrap -stack build +$ cd bootstrap/ +$ stack build ``` + To test: + ```bash -stack test +$ stack test ``` + To install: + ```bash -stack install +$ stack install ``` -On Linux, the above command installs `fpm` to `${HOME}/.local/bin`. +On Linux, the above command installs `fpm` to `${HOME}/.local/bin/`. ### Creating a new project -Creating a new fpm project is as simple as running the command `fpm new project_name`. -This will create a new folder in your current directory with the following contents -and initialized as a git repository. +Creating a new *fpm* project is as simple as running the command +`fpm new project_name`. This will create a new folder in your current directory +with the following contents and initialized as a git repository. -* `fpm.toml` with your project's name and some default standard meta-data -* `README.md` with your project's name +* `fpm.toml` – with your project’s name and some default standard meta-data +* `README.md` – with your project’s name * `.gitgnore` -* `src/project_name.f90` with a simple hello world subroutine -* `app/main.f90` (if `--with-executable` flag used) a program that calls the subroutine -* `test/main.f90` (if `--with-test` flag used) an empty test program +* `src/project_name.f90` – with a simple hello world subroutine +* `app/main.f90` (if `--with-executable` flag used) – a program that calls the subroutine +* `test/main.f90` (if `--with-test` flag used) – an empty test program ### Building your Fortran project with fpm -fpm understands the basic commands: +*fpm* understands the basic commands: -* `fpm build` - build your library, executables and tests -* `fpm run` - run executables -* `fpm test`- run tests +* `fpm build` – build your library, executables and tests +* `fpm run` – run executables +* `fpm test` – run tests The command `fpm run` can optionally accept the name of the specific executable to run, as can `fpm test`; like `fpm run specifc_executable`. Command line |