Skip to content

Add brief explanation on how to include stdlib in a Makefile #781

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Apr 8, 2024
Merged

Add brief explanation on how to include stdlib in a Makefile #781

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
672cd36
Add brief explanation on how to include stdlib in a Makefile
Apr 2, 2024
86c9bef
Move fpm usage description and include Cmake installation paths
Apr 2, 2024
2a648a8
Update README.md
jannisteunissen Apr 2, 2024
1cb5e9a
Merge branch 'fortran-lang:master' into master
jannisteunissen Apr 4, 2024
ecf85d0
Add pkg-config usage in Makefile
jannisteunissen Apr 4, 2024
d288010
Update line about build_dir
jannisteunissen Apr 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 35 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,22 +201,10 @@ fpm run --example prog
with `prog` being the name of the example program (e.g., `example_sort`).


To use `stdlib` within your `fpm` project, add the following lines to your `fpm.toml` file:
```toml
[dependencies]
stdlib = { git="https://github.com/fortran-lang/stdlib", branch="stdlib-fpm" }
```

> **Warning**
>
> Fpm 0.9.0 and later implements stdlib as a *metapackage*.
> To include the standard library metapackage, change the dependency to:
> `stdlib = "*"`.
>
> [see also](https://fpm.fortran-lang.org/spec/metapackages.html)

## Using stdlib in your project

### Using stdlib with CMake

The stdlib project exports CMake package files and pkg-config files to make stdlib usable for other projects.
The package files are located in the library directory in the installation prefix.

Expand All @@ -235,6 +223,39 @@ target_link_libraries(
To make the installed stdlib project discoverable add the stdlib directory to the ``CMAKE_PREFIX_PATH``.
The usual install location of the package files is ``$PREFIX/lib/cmake/fortran_stdlib``.

### Using stdlib with fpm

To use `stdlib` within your `fpm` project, add the following lines to your `fpm.toml` file:
```toml
[dependencies]
stdlib = { git="https://github.com/fortran-lang/stdlib", branch="stdlib-fpm" }
```

> **Warning**
>
> Fpm 0.9.0 and later implements stdlib as a *metapackage*.
> To include the standard library metapackage, change the dependency to:
> `stdlib = "*"`.
>
> [see also](https://fpm.fortran-lang.org/spec/metapackages.html)

### Using stdlib with a regular Makefile

After the library has been built, it can be included in a regular Makefile.
If the library has been installed in a directory inside the compiler's search path,
only a flag `-lfortran_stdlib` is required to link against `libfortran_stdlib.a` or `libfortran_stdlib.so`.
If the installation directory is not in the compiler's search path, one can add for example
```make
libdir=${install_dir}/lib
moduledir=${install_dir}/include/fortran_stdlib/<compiler name and version>
```
Here it is assumed that the compiler will look for libraries in `libdir` and for module files in `moduledir`.
The library can also be included from a build directory without installation:
```make
libdir=$(build_dir)/src
moduledir=$(build_dir)/src/mod_files
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here it would be good to see an example of how libdir and moduledir would be used inside the makefile to affect the compiler flags.


Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we add a something like below, to cover the case of compiling in a shell script or naively from the command line? I don't have much expertise on build systems, and often write small scripts to build programs.

Using stdlib when compiling within a script, or on the command line

This example uses pkg-config to manage the compiler flags.

export PKG_CONFIG_PATH=${install_dir}/lib/pkgconfig:$PKG_CONFIG_PATH
export STDLIB_CFLAGS=$(pkg-config --cflags fortran_stdlib)
export STDLIB_LIBS=$(pkg-config --libs fortran_stdlib)

export FC=gfortran
export FFLAGS="-O3 -flto"

# Compile
$FC $FFLAGS -c $STDLIB_CFLAGS my_program.f90
# Link
$FC $FFLAGS -o my_program my_program.o $STDLIB_LIBS

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the information on pkg-config would certainly be nice to include as well, I can do that. I am a little hesitant to include actual compile rules, since these will depend on the particular compiler used and perhaps also on other things. To explain this clearly to people who are not familiar with Makefiles and compilation rules could take too much space. Instead, it could be nice to include a few worked-out usage examples with Makefiles in a separate location.

## Documentation

Documentation is a work in progress (see issue [#4](https://github.com/fortran-lang/stdlib/issues/4)) but already available at [stdlib.fortran-lang.org](https://stdlib.fortran-lang.org).
Expand Down