diff --git a/README.md b/README.md index 2a7f336ae..6180bea0e 100644 --- a/README.md +++ b/README.md @@ -201,6 +201,30 @@ fpm run --example prog with `prog` being the name of the example program (e.g., `example_sort`). +## 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. + +For CMake builds of stdlib you can find a local installation with + +```cmake +find_package(fortran_stdlib REQUIRED) +... +target_link_libraries( + ${PROJECT_NAME} + PRIVATE + fortran_stdlib::fortran_stdlib +) +``` + +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] @@ -215,25 +239,51 @@ stdlib = { git="https://github.com/fortran-lang/stdlib", branch="stdlib-fpm" } > > [see also](https://fpm.fortran-lang.org/spec/metapackages.html) -## Using stdlib in your project +### Using stdlib with a regular Makefile -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. +After the library has been built, it can be included in a regular Makefile. +The recommended way to do this is using the [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) tool, for which an example is shown below. +```make +# Necessary if the installation directory is not in PKG_CONFIG_PATH +install_dir := path/to/install_dir +export PKG_CONFIG_PATH := $(install_dir)/lib/pkgconfig:$(PKG_CONFIG_PATH) -For CMake builds of stdlib you can find a local installation with +STDLIB_CFLAGS := `pkg-config --cflags fortran_stdlib` +STDLIB_LIBS := `pkg-config --libs fortran_stdlib` -```cmake -find_package(fortran_stdlib REQUIRED) +# Example definition of Fortran compiler and flags +FC := gfortran +FFLAGS := -O2 -Wall -g + +# Definition of targets etc. ... -target_link_libraries( - ${PROJECT_NAME} - PRIVATE - fortran_stdlib::fortran_stdlib -) + +# Example rule to compile object files from .f90 files +%.o: %.f90 + $(FC) -c -o $@ $< $(FFLAGS) $(STDLIB_CFLAGS) + +# Example rule to link an executable from object files +%: %.o + $(FC) -o $@ $^ $(FFLAGS) $(STDLIB_LIBS) + ``` -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``. +The same can also be achieved without pkg-config. +If the library has been installed in a directory inside the compiler's search path, +only a flag `-lfortran_stdlib` is required. +If the installation directory is not in the compiler's search path, one can add for example +```make +install_dir := path/to/install_dir +libdir := $(install_dir)/lib +moduledir := $(install_dir)/include/fortran_stdlib/ +``` +The linker should then look for libraries in `libdir` (using e.g.`-L$(libdir)`) and the compiler should look for module files in `moduledir` (using e.g. `-I$(moduledir)`). +Alternatively, the library can also be included from a build directory without installation with +```make +build_dir := path/to/build_dir +libdir := $(build_dir)/src +moduledir := $(build_dir)/src/mod_files +``` ## Documentation