Update building programs book

[awvwgk]

I think the build-tools section of the building programs minibook is a bit short and the make example contains a few common gotchas, therefore I tried to update it.

I also started some minimal introductions to meson and CMake to explain the concept of high-level build systems in comparison to make. Since it is an introductory book I didn't went to much into details on using those, as this might be something for an intermediate or advanced guide.

Changes:

• replace hyphens by endashs emdashs
• use correct external link declaration
• rename the example source file to functions
• correct name of the generate module file set to user_functions
• extend the build-tools page with a detailed guide on make
  • explain concept of recursively defined variables which is commonly misused in make
• add a short guide on meson
• add a short guide on CMake

[certik]

Quite frankly, why don't we replace that section with fpm?

The document (I thought) is tailored for new users. New users either want to start a project from scratch (thus fpm I think will work already) or they wan to contribute to an already existing project, but then they have to follow whatever build system the existing project uses.

[milancurcic]

Quite frankly, why don't we replace that section with fpm?

I agree that this is the way to go.

Although it may not be quite adequate yet (two implementations, unstable spec and behavior, unimplemented functionality in the Fortran client), this would help adopt new fpm users. New Fortran users would go straight to fpm.

I recommend that:

1. We review, edit, and merge this PR;
2. We work on the fpm guide;
3. We put the fpm guide first, and we keep the existing guide as "Other build tools" or similar. It's useful to keep it.

[awvwgk]

There is some diversity in build tools available, I think they should be discussed at least briefly to give some guidance to a beginner. Also, there are only few projects offering help or useful insights for the build systems they are using. I was motivated to look into this guide after a friend asked me about a good read with some more depth on compiling, linking and building.

[awvwgk]

An fpm guide wouldn't need any of the information in this particular minibook, writing a separate book on learning Fortran with fpm is the better call in my opinion.

[LKedward]

An fpm guide wouldn't need any of the information in this particular minibook, writing a separate book on learning Fortran with fpm is the better call in my opinion.

I share this sentiment

[LKedward]

As someone who struggled to find adequate online material when learning make and other systems for Fortran (I still struggle with cmake), I think this is a good addition to this particular minibook. A separate minibook for fpm seems more appropriate - when ready this can then supplant this minibook as the recommended beginners' guide.

Edit: I see that Milan has essentially proposed the same thing. I think it would be good to get more users to fpm with a good beginner's minibook here; there may need to be a warning regarding the maturity of fpm and it may be worth waiting for at least a first beta release milestone of the fortran implementation.

[awvwgk]

As someone who struggled to find adequate online material when learning make and other systems for Fortran (I still struggle with cmake), I think this is a good addition to this particular minibook.

I added a few sections on common gotchas in make as well. If wanted I can also expand on some of the more useful make features, like vpath, string manipulation or recursive make.

[ivan-pi]

As someone who struggled to find adequate online material when learning make and other systems for Fortran (I still struggle with cmake), I think this is a good addition to this particular minibook. A separate minibook for fpm seems more appropriate - when ready this can then supplant this minibook as the recommended beginners' guide.

I second these thoughts. The available resources on Cmake and make targeted at Fortran are scarce. Most of the time I resorted to just adapting the makefiles from existing Fortran projects, not knowing what exactly are they doing. Having the minibooks in one place will hopefully make it easier for beginners to progress from small projects to intermediate and large projects where a build system is needed (at least until fpm is mature).

[certik]

Sounds good, I agree with the comments above.

…

On Sat, Oct 24, 2020, at 8:35 AM, Ivan wrote: > As someone who struggled to find adequate online material when learning `make` and other systems for Fortran (I still struggle with `cmake`), I think this is a good addition to this particular minibook. A separate minibook for fpm seems more appropriate - when ready this can then supplant this minibook as the recommended beginners' guide. I second these thoughts. The available resources on Cmake and make targeted at Fortran are scarce. Most of the time I resorted to just adapting the makefiles from existing Fortran projects, not knowing what exactly are they doing. Having the minibooks in one place will hopefully make it easier for beginners to progress from small projects to intermediate and large projects where a build system is needed (at least until fpm is mature). — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#156 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAFAWEAH224H2ZKVI3F7OTSMLQ4DANCNFSM4S4YMOFA>.

[awvwgk]

This PR has been stale for almost a month now. Is there still interest in this?

[milancurcic]

Thank you for the nudge, @awvwgk, I forgot about this PR.

I reviewed it again and I like the changes.

I only suggest that we replace en dashes with em dashes. En dashes are typically used for ranges and em dashes to break up sentences, see this en dash guide and this em dash guide.

Originally, I would have suggested not using spaces around em dashes, which tend to be used only in newspapers with narrow columns. This allows them to break across lines. However, I changed my mind about this because our website is mobile friendly and can have narrow columns on smaller devices. Spaces around em dash can thus improve readability on such devices.

[milancurcic]

With no objections, I'll go ahead and merge this.