Merge pull request #781 from jannisteunissen/master

Add brief explanation on how to include stdlib in a Makefile

Author: gareth-nx

Diff for: 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/<compiler name and version>
+```
+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