Add brief explanation on how to include stdlib in a Makefile

[jannisteunissen]

The current documentation on how to use stdlib in a project focuses on Cmake, see https://github.com/fortran-lang/stdlib?tab=readme-ov-file#using-stdlib-in-your-project

It can seem as is you actually need CMAKE to include stdlib (I got this impression). I think it would also be helpful to describe how to include stdlib in a regular makefile. This small change includes such documentation. I was not 100% sure about the paths: is it correct that the library is always in <build_folder>/src?

[jvdp1]

Thank you @jannisteunissen . LGTM. It might be good to move also the lines 204-216 in this section, such that the section "Using stdlib in your project" contains the directives for CMake, Make, and fpm.

[perazz]

Apologies I'm no pkg-config expert. However, I think the reader may think that stdlib can be built directly using a makefile with this PR. So I would suggest to make it clear what step these instructions apply to:

1. build it with CMake <- necessary anyways
   <-- current PR refers to here
2. install it to a desired folder (cmake --install . --prefix=/path/to/my/installation)
   <-- paths here are probably the more canonical way
3. use/link against it

The reported paths look OK (I haven't tested it). However, After install, we have a different scenario, because after a CMake build+install, folders are like

stdlib/config/template.pc

Lines 2 to 4 in e88daa3

	libdir=${prefix}/@CMAKE_INSTALL_LIBDIR@
	includedir=${prefix}/@CMAKE_INSTALL_INCLUDEDIR@
	moduledir=${prefix}/@CMAKE_INSTALL_MODULEDIR@

i.e., for example:

libdir=${prefix}/lib
includedir=${prefix}/include
moduledir=${prefix}/include/fortran_stdlib/GNU-13.2.0

So if the user has run cmake --install, they may not be correct (the build folder is usually deleted after an installation).

Also: an stdlib-fpm install is not currently supported and I think it's a good idea to have, I will open a PR for this so that then, one may also use the installed static library from the fpm branch.

[jannisteunissen]

Thanks for explaining the directory structure. I will update this pull request. One question for @perazz :

includedir=${prefix}/include
moduledir=${prefix}/include/fortran_stdlib/GNU-13.2.0

Is there any need to specify this 'includedir'? I thought only the module path would be necessary.

[perazz]

I would not worry about the general include folder, as I don't think that stdlib is ever going to include C headers

[perazz]

LGTM. Thank you @jannisteunissen

[jvdp1]

LGTM. Thank you @jannisteunissen .

Let wait a few days, and if there are no more comments, we could merge it.

[gareth-nx]

It might be useful to have more explicit instructions for people who get confused compiling things (like me). I didn't find it immediately obvious how go from the current draft content to compiling programs.

For what it's worth I would tend to do something like this, which is probably derived from since-deleted stdlib documentation.

export PKG_CONFIG_PATH=/home/gareth/Code_Experiments/fortran/stdlib/stdlib/local_install_gfortran/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 

Perhaps my point could be addressed if we add another line showing how the variables should affect the calls to the compiler?

[jvdp1]

from since-deleted stdlib documentation.

Which doc do you refer to?

[gareth-nx]

@jvdp1 I just dug out an old variant of the README -- the relevant section is copied below.

Using stdlib in your project

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

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.

For non-CMake build systems (like make) you can use the exported pkg-config file by setting PKG_CONFIG_PATH to include the directory containing the exported pc-file.
The usual install location of the pc-file is $PREFIX/lib/pkgconfig.
In make you can obtain the required compile and link arguments with

STDLIB_CFLAGS := $(shell pkg-config --cflags fortran_stdlib)
STDLIB_LIBS := $(shell pkg-config --libs fortran_stdlib)

[gareth-nx]

Thanks for following this up, it could help make stdlib more accessible.

[gareth-nx]

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 

[jannisteunissen]

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.

[gareth-nx]

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.

[jalvesz]

Just a small cosmetic suggestion: maybe use this: https://gist.github.com/pierrejoubert73/902cc94d79424356a8d20be2b382e1ab to add collapsible regions in the readme. It would be a good way to keep the view of the online version compact yet enable adding complete examples for each use case (?)

Question: does pkg-config work on Windows? if so, a batch equivalent of the shell example could be useful.

[jannisteunissen]

Update: I have now included an example of how to use pkg-config in a Makefile, which includes examples of compilation rules. I have left out details about defining targets etc, so I believe it is fine without a 'foldable' section.

I have also clarified how the libdir and moduledir could be used without pkg-config.