Update of the minibook on building programs: #99
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Text split into separate "chapters"/"sections" - Applying consistent mark-up for code sections and keywords and such - Applying most suggestions from the reviews (I have kept the "tabulate.f90" mostly as it was, but I have changed the name of the module to make it a bit clearer. - Small textual changes in places
|
#build_preview |
|
This PR has been built with Jekyll and can be previewed at: https://fortran-lang.org/pr/99/ |
|
@arjenmarkus does this PR supersede the previous one (#90)? |
|
@LKedward do you know why this preview didn't build? The preview site doesn't load for me. |
It's working for me - can you try on another device, maybe with mobile internet? |
|
@milancurcic - also give https://fortran-lang.org/pr/99/index.html a try. |
|
I think this looks great, thank you. Once fpm is more usable, we can update the tutorial to show how to do this using fpm. |
milancurcic
requested review from
LKedward,
milancurcic,
everythingfunctional and
jvdp1
|
Hi Milan,
yes, this is the result of the suggestions made earlier by Jérémie and
others, and of splitting up the text based on the recipe by Laurence.
Regards,
Arjen
Op vr 5 jun. 2020 om 21:46 schreef Milan Curcic <notifications@github.com>:
… @arjenmarkus <https://github.com/arjenmarkus> does this PR supersede the
previous one (#90
<#90>)?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#99 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAN6YRYX6AKRXFY6MBYLTJDRVFDSFANCNFSM4NU76QZQ>
.
|
milancurcic
approved these changes
Jun 6, 2020
There was a problem hiding this comment.
@arjenmarkus Thanks a lot. I love your writing style. I left several minor suggestions.
I noticed that many code listings/snippets are entirely indented by 4 or 8 spaces. Are these indentations necessary?
| 2. Distribute a pre-built executable program | ||
| 3. Distribute static or dynamic libraries that people can use | ||
|
|
||
| ad 1. |
There was a problem hiding this comment.
What does ad. 1 (and so on) mean? Perhaps better to explicitly type out each item for each explanation
There was a problem hiding this comment.
Oh, I thought this kind of referencing was "universal" - "ad 1" means "look above for a concise description, here is a more extensive explanation". But that may be a neerlandicism ;).
|
@arjenmarkus As you review the suggestions, click on "Commit suggestion" to automatically incorporate it in this PR, or just "Resolve conversation" to dismiss it. |
everythingfunctional
approved these changes
Jun 7, 2020
jvdp1
approved these changes
Jun 7, 2020
LKedward
approved these changes
Jun 7, 2020
|
Hi everyone,
Thanks for the suggestions and the approval. I hope to find time in the
next few days (let's be careful with promises) to incorporate these
suggestions. (I confess being a trifle lazy when it comes to hunting down
the relevant URLs :)).
Regards,
Arjen
Op zo 7 jun. 2020 om 13:04 schreef Laurence Kedward <
notifications@github.com>:
… ***@***.**** approved this pull request.
Thanks Arjen for your work on this - it's looking really good 👍
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#99 (review)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAN6YR6AIQVUPIOUL34AS2TRVNX2XANCNFSM4NU76QZQ>
.
|
|
Hi Milan,
wrt the indentation, hm, no, not really - at least I guess they are
superfluous now that the blocks are marked with the programming language. I
did not realise the indentation could be removed. That could certainly be a
cosmetic update.
Regards,
Arjen
Op za 6 jun. 2020 om 22:08 schreef Milan Curcic <notifications@github.com>:
… ***@***.**** approved this pull request.
@arjenmarkus <https://github.com/arjenmarkus> Thanks a lot. I love your
writing style. I left several minor suggestions.
I noticed that many code listings/snippets are entirely indented by 4 or 8
spaces. Are these indentations necessary?
------------------------------
In learn/building_programs/build_tools.md
<#99 (comment)>
:
> +* The `make` utility is a classical tool that uses instructions about
+how the various components of a program depend on each other to
+efficiently compile and link the program (or programs). It takes a
+so-called `Makefile` that contains the dependencies.
+
+ Simply put:
+
+ If a program file is older than any of the libraries and object files
+it depends on, the make utility knows it has to rebuild it and goes on
+to look at the libraries and object files - are any out of date?
+
+ If an object file is older than the corresponding source file, the
+make utility knows it has to compile the source file.
+
+* Integrated development tools take care of many of the above details. A
+popular tool on Windows is MicroSoft's Visual Studio, but others exist,
⬇️ Suggested change
-popular tool on Windows is MicroSoft's Visual Studio, but others exist,
+popular cross-platform tool is Microsoft's [Visual Studio Code](https://code.visualstudio.com/), but others exist,
------------------------------
In learn/building_programs/build_tools.md
<#99 (comment)>
:
> +how the various components of a program depend on each other to
+efficiently compile and link the program (or programs). It takes a
+so-called `Makefile` that contains the dependencies.
+
+ Simply put:
+
+ If a program file is older than any of the libraries and object files
+it depends on, the make utility knows it has to rebuild it and goes on
+to look at the libraries and object files - are any out of date?
+
+ If an object file is older than the corresponding source file, the
+make utility knows it has to compile the source file.
+
+* Integrated development tools take care of many of the above details. A
+popular tool on Windows is MicroSoft's Visual Studio, but others exist,
+such as Eclipse (Photran) and Code::Blocks. They offer a graphical
⬇️ Suggested change
-such as Eclipse (Photran) and Code::Blocks. They offer a graphical
+such as [Atom](https://atom.io/), [Eclipse Photran](https://www.eclipse.org/photran/), and [Code::Blocks](http://www.codeblocks.org/). They offer a graphical
------------------------------
In learn/building_programs/build_tools.md
<#99 (comment)>
:
> + Simply put:
+
+ If a program file is older than any of the libraries and object files
+it depends on, the make utility knows it has to rebuild it and goes on
+to look at the libraries and object files - are any out of date?
+
+ If an object file is older than the corresponding source file, the
+make utility knows it has to compile the source file.
+
+* Integrated development tools take care of many of the above details. A
+popular tool on Windows is MicroSoft's Visual Studio, but others exist,
+such as Eclipse (Photran) and Code::Blocks. They offer a graphical
+user-interface, but are often very specific for the compiler and
+platform.
+
+* Maintenance tools like autotools and CMake can generate makefiles or
⬇️ Suggested change
-* Maintenance tools like autotools and CMake can generate makefiles or
+* Maintenance tools like autotools and CMake can generate Makefiles or
------------------------------
In learn/building_programs/distributing.md
<#99 (comment)>
:
> @@ -0,0 +1,136 @@
+---
+layout: book
+title: Distributing your programs
+permalink: /learn/building_programs/distributing
+---
+
+When you distributed your programs, there are a number of options you can
⬇️ Suggested change
-When you distributed your programs, there are a number of options you can
+When you distribute your programs, there are a number of options you can
------------------------------
In learn/building_programs/distributing.md
<#99 (comment)>
:
> @@ -0,0 +1,136 @@
+---
+layout: book
+title: Distributing your programs
+permalink: /learn/building_programs/distributing
+---
+
+When you distributed your programs, there are a number of options you can
+choose from:
+
+1. Distribute the entire source code
+2. Distribute a pre-built executable program
+3. Distribute static or dynamic libraries that people can use
+
+ad 1.
What does ad. 1 (and so on) mean? Perhaps better to explicitly type out
each item for each explanation
------------------------------
In learn/building_programs/linking_pieces.md
<#99 (comment)>
:
> +the function in the right way. It might be that you made a mistake and
+called the function with two arguments instead of one. If the compiler
+does not know anything about the function's interface, then it cannot
+check anything.
+
+The second step invokes the compiler in such a way that:
+
+* it compiles the file "tabulate.f90" (using the module file);
+* it invokes the linker to combine the object files tabulate.o and function.o into an
+executable program - with the default name "a.out" or "a.exe" (if you
+want a different name, use the option "-o").
+
+What you do not see in general is that the linker also adds a number of
+extra files in this link step, the run-time libraries. These run-time
+libraries contain all the "standard" stuff - low-level routines that do
+the input and output to screen, the `sine` function and much more.
⬇️ Suggested change
-the input and output to screen, the `sine` function and much more.
+the input and output to screen, the `sin` function and much more.
------------------------------
In learn/building_programs/managing_libraries.md
<#99 (comment)>
:
> +libraries remain outside the executable program and as a consequence
+can be replaced without rebulding the entire program. Compilers and
+indeed the operating system itself rely heavily on such dynamic
+libraries. You could consider dynamic libraries as a sort of executable
+programs that need a bit of help to be run.
+
+Building dynamic libraries works slightly differently from building
+static libraries: you use the compiler/linker instead of a tool
+like `ar` or `lib`.
+
+On Linux:
+
+```shell
+ $ gfortran -fpic -c file1.f90 file2.f90
+ $ gfortran -fpic -c file3.f90 ...
+ $ gfortran -shared --o supportlib.so file1.o file2.o file3.o ...
⬇️ Suggested change
- $ gfortran -shared --o supportlib.so file1.o file2.o file3.o ...
+ $ gfortran -shared -o supportlib.so file1.o file2.o file3.o ...
------------------------------
In learn/building_programs/managing_libraries.md
<#99 (comment)>
:
> +
+```shell
+ $ gfortran -o tabulate tabulate.f90 function.dll
+```
+
+The DLL and the .mod file are used to build the executable program
+with checks on the function's interface, the right name and the reference
+to "a" DLL, called "function.dll".
+
+You can replace the shared library "function.dll" by another one, implementing
+a different function "f". Of course, you need to be careful to use the correct
+interface for this function. The compiler/linker are not invoked anymore, so they
+can do no checking.
+
+## Windows and Intel Fortran
+The setup is the same as with GNU/Linux, but on Windows it is necessary
⬇️ Suggested change
-The setup is the same as with GNU/Linux, but on Windows it is necessary
+The setup is the same as with Linux, but on Windows it is necessary
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#99 (review)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAN6YRYLJAJZQDC6GSNHXVLRVKO2NANCNFSM4NU76QZQ>
.
|
Co-authored-by: Milan Curcic <caomaco@gmail.com>
Co-authored-by: Milan Curcic <caomaco@gmail.com>
Co-authored-by: Milan Curcic <caomaco@gmail.com>
Co-authored-by: Milan Curcic <caomaco@gmail.com>
Co-authored-by: Milan Curcic <caomaco@gmail.com>
Co-authored-by: Milan Curcic <caomaco@gmail.com>
Co-authored-by: Milan Curcic <caomaco@gmail.com>
Co-authored-by: Brad Richardson <everythingfunctional@protonmail.com>
|
How to resolve this conflict? |
|
Hi everyone,
just did my best to get the remaining suggestions in. I do not know exactly
what to do with the conflict in learn.yml, so I would like your advice on
this.
Regards,
Arjen
Op ma 8 jun. 2020 om 08:45 schreef Arjen Markus <arjen.markus895@gmail.com>:
… Hi Milan,
wrt the indentation, hm, no, not really - at least I guess they are
superfluous now that the blocks are marked with the programming language. I
did not realise the indentation could be removed. That could certainly be a
cosmetic update.
Regards,
Arjen
Op za 6 jun. 2020 om 22:08 schreef Milan Curcic ***@***.***
>:
> ***@***.**** approved this pull request.
>
> @arjenmarkus <https://github.com/arjenmarkus> Thanks a lot. I love your
> writing style. I left several minor suggestions.
>
> I noticed that many code listings/snippets are entirely indented by 4 or
> 8 spaces. Are these indentations necessary?
> ------------------------------
>
> In learn/building_programs/build_tools.md
> <#99 (comment)>
> :
>
> > +* The `make` utility is a classical tool that uses instructions about
>
> +how the various components of a program depend on each other to
>
> +efficiently compile and link the program (or programs). It takes a
>
> +so-called `Makefile` that contains the dependencies.
>
> +
>
> + Simply put:
>
> +
>
> + If a program file is older than any of the libraries and object files
>
> +it depends on, the make utility knows it has to rebuild it and goes on
>
> +to look at the libraries and object files - are any out of date?
>
> +
>
> + If an object file is older than the corresponding source file, the
>
> +make utility knows it has to compile the source file.
>
> +
>
> +* Integrated development tools take care of many of the above details. A
>
> +popular tool on Windows is MicroSoft's Visual Studio, but others exist,
>
>
> ⬇️ Suggested change
>
> -popular tool on Windows is MicroSoft's Visual Studio, but others exist,
>
> +popular cross-platform tool is Microsoft's [Visual Studio Code](https://code.visualstudio.com/), but others exist,
>
>
> ------------------------------
>
> In learn/building_programs/build_tools.md
> <#99 (comment)>
> :
>
> > +how the various components of a program depend on each other to
>
> +efficiently compile and link the program (or programs). It takes a
>
> +so-called `Makefile` that contains the dependencies.
>
> +
>
> + Simply put:
>
> +
>
> + If a program file is older than any of the libraries and object files
>
> +it depends on, the make utility knows it has to rebuild it and goes on
>
> +to look at the libraries and object files - are any out of date?
>
> +
>
> + If an object file is older than the corresponding source file, the
>
> +make utility knows it has to compile the source file.
>
> +
>
> +* Integrated development tools take care of many of the above details. A
>
> +popular tool on Windows is MicroSoft's Visual Studio, but others exist,
>
> +such as Eclipse (Photran) and Code::Blocks. They offer a graphical
>
>
> ⬇️ Suggested change
>
> -such as Eclipse (Photran) and Code::Blocks. They offer a graphical
>
> +such as [Atom](https://atom.io/), [Eclipse Photran](https://www.eclipse.org/photran/), and [Code::Blocks](http://www.codeblocks.org/). They offer a graphical
>
>
> ------------------------------
>
> In learn/building_programs/build_tools.md
> <#99 (comment)>
> :
>
> > + Simply put:
>
> +
>
> + If a program file is older than any of the libraries and object files
>
> +it depends on, the make utility knows it has to rebuild it and goes on
>
> +to look at the libraries and object files - are any out of date?
>
> +
>
> + If an object file is older than the corresponding source file, the
>
> +make utility knows it has to compile the source file.
>
> +
>
> +* Integrated development tools take care of many of the above details. A
>
> +popular tool on Windows is MicroSoft's Visual Studio, but others exist,
>
> +such as Eclipse (Photran) and Code::Blocks. They offer a graphical
>
> +user-interface, but are often very specific for the compiler and
>
> +platform.
>
> +
>
> +* Maintenance tools like autotools and CMake can generate makefiles or
>
>
> ⬇️ Suggested change
>
> -* Maintenance tools like autotools and CMake can generate makefiles or
>
> +* Maintenance tools like autotools and CMake can generate Makefiles or
>
>
> ------------------------------
>
> In learn/building_programs/distributing.md
> <#99 (comment)>
> :
>
> > @@ -0,0 +1,136 @@
>
> +---
>
> +layout: book
>
> +title: Distributing your programs
>
> +permalink: /learn/building_programs/distributing
>
> +---
>
> +
>
> +When you distributed your programs, there are a number of options you can
>
>
> ⬇️ Suggested change
>
> -When you distributed your programs, there are a number of options you can
>
> +When you distribute your programs, there are a number of options you can
>
>
> ------------------------------
>
> In learn/building_programs/distributing.md
> <#99 (comment)>
> :
>
> > @@ -0,0 +1,136 @@
>
> +---
>
> +layout: book
>
> +title: Distributing your programs
>
> +permalink: /learn/building_programs/distributing
>
> +---
>
> +
>
> +When you distributed your programs, there are a number of options you can
>
> +choose from:
>
> +
>
> +1. Distribute the entire source code
>
> +2. Distribute a pre-built executable program
>
> +3. Distribute static or dynamic libraries that people can use
>
> +
>
> +ad 1.
>
>
> What does ad. 1 (and so on) mean? Perhaps better to explicitly type out
> each item for each explanation
> ------------------------------
>
> In learn/building_programs/linking_pieces.md
> <#99 (comment)>
> :
>
> > +the function in the right way. It might be that you made a mistake and
>
> +called the function with two arguments instead of one. If the compiler
>
> +does not know anything about the function's interface, then it cannot
>
> +check anything.
>
> +
>
> +The second step invokes the compiler in such a way that:
>
> +
>
> +* it compiles the file "tabulate.f90" (using the module file);
>
> +* it invokes the linker to combine the object files tabulate.o and function.o into an
>
> +executable program - with the default name "a.out" or "a.exe" (if you
>
> +want a different name, use the option "-o").
>
> +
>
> +What you do not see in general is that the linker also adds a number of
>
> +extra files in this link step, the run-time libraries. These run-time
>
> +libraries contain all the "standard" stuff - low-level routines that do
>
> +the input and output to screen, the `sine` function and much more.
>
>
> ⬇️ Suggested change
>
> -the input and output to screen, the `sine` function and much more.
>
> +the input and output to screen, the `sin` function and much more.
>
>
> ------------------------------
>
> In learn/building_programs/managing_libraries.md
> <#99 (comment)>
> :
>
> > +libraries remain outside the executable program and as a consequence
>
> +can be replaced without rebulding the entire program. Compilers and
>
> +indeed the operating system itself rely heavily on such dynamic
>
> +libraries. You could consider dynamic libraries as a sort of executable
>
> +programs that need a bit of help to be run.
>
> +
>
> +Building dynamic libraries works slightly differently from building
>
> +static libraries: you use the compiler/linker instead of a tool
>
> +like `ar` or `lib`.
>
> +
>
> +On Linux:
>
> +
>
> +```shell
>
> + $ gfortran -fpic -c file1.f90 file2.f90
>
> + $ gfortran -fpic -c file3.f90 ...
>
> + $ gfortran -shared --o supportlib.so file1.o file2.o file3.o ...
>
>
> ⬇️ Suggested change
>
> - $ gfortran -shared --o supportlib.so file1.o file2.o file3.o ...
>
> + $ gfortran -shared -o supportlib.so file1.o file2.o file3.o ...
>
>
> ------------------------------
>
> In learn/building_programs/managing_libraries.md
> <#99 (comment)>
> :
>
> > +
>
> +```shell
>
> + $ gfortran -o tabulate tabulate.f90 function.dll
>
> +```
>
> +
>
> +The DLL and the .mod file are used to build the executable program
>
> +with checks on the function's interface, the right name and the reference
>
> +to "a" DLL, called "function.dll".
>
> +
>
> +You can replace the shared library "function.dll" by another one, implementing
>
> +a different function "f". Of course, you need to be careful to use the correct
>
> +interface for this function. The compiler/linker are not invoked anymore, so they
>
> +can do no checking.
>
> +
>
> +## Windows and Intel Fortran
>
> +The setup is the same as with GNU/Linux, but on Windows it is necessary
>
>
> ⬇️ Suggested change
>
> -The setup is the same as with GNU/Linux, but on Windows it is necessary
>
> +The setup is the same as with Linux, but on Windows it is necessary
>
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <#99 (review)>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AAN6YRYLJAJZQDC6GSNHXVLRVKO2NANCNFSM4NU76QZQ>
> .
>
|
|
Hi @arjenmarkus, many thanks. |
|
This PR has been built with Jekyll and can be previewed at: https://fortran-lang.org/pr/99/ |
|
Hi @LKedward, thanks - got the copy now. (I am still learning the workflow
:))
Regards,
Arjen
Op wo 17 jun. 2020 om 10:13 schreef Laurence Kedward <
notifications@github.com>:
… Hi @arjenmarkus <https://github.com/arjenmarkus>, many thanks.
I've resolved the conflict on github - you will need to run git pull on
your local copy if you intend to do any more edits in your local copy.
I will update the #build_preview with the latest changes for a final check.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#99 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAN6YR4TEBNL4IAIFOCOLLDRXB3KXANCNFSM4NU76QZQ>
.
|
|
This PR has been built with Jekyll and can be previewed at: https://fortran-lang.org/pr/99/ |
milancurcic
reviewed
Jun 17, 2020
milancurcic
reviewed
Jun 17, 2020
milancurcic
approved these changes
Jun 17, 2020
|
Thank you for everything. |
LKedward
reviewed
Jun 17, 2020
LKedward
reviewed
Jun 17, 2020
LKedward
reviewed
Jun 17, 2020
LKedward
reviewed
Jun 17, 2020
To be accurate: Jérémie Vandenplas Co-authored-by: Milan Curcic <caomaco@gmail.com>
Co-authored-by: Milan Curcic <caomaco@gmail.com>
Co-authored-by: Laurence Kedward <laurence.kedward@bristol.ac.uk>
Co-authored-by: Laurence Kedward <laurence.kedward@bristol.ac.uk>
Co-authored-by: Laurence Kedward <laurence.kedward@bristol.ac.uk>
Co-authored-by: Laurence Kedward <laurence.kedward@bristol.ac.uk>
|
Hi everyone,
just committed the changes - I should now close the pull request, I guess?
Regards,
Arjen
Op wo 17 jun. 2020 om 15:46 schreef Laurence Kedward <
notifications@github.com>:
… ***@***.**** commented on this pull request.
------------------------------
In learn/building_programs/distributing.md
<#99 (comment)>
:
> + !DEC$ ATTRIBUTES DLLEXPORT :: f
+ real, intent(in) :: x
+
+ ... TO BE FILLED IN ...
+
+ end function f
+ end module user_functions
+```
+
+* Provide a basic build script with a command like:
+
+```shell
+ gfortran -o function.dll function.f90 -shared
+```
+
+ or:
Okay, removing the indent fixes it.
⬇️ Suggested change
- or:
+or:
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#99 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAN6YRZMTE2CNKZKBI4LU33RXDCMHANCNFSM4NU76QZQ>
.
|
|
Thanks @arjenmarkus - this looks good! Since you're happy with it, I will merge. |
|
#delete_preview |
|
The preview build for this PR has now been deleted. |
|
Nice to see this on the website :).
Regards,
Arjen
Op wo 17 jun. 2020 om 16:30 schreef github-actions[bot]
<notifications@github.com>:
…
The preview build for this PR has now been deleted.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or unsubscribe.
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
mostly as it was, but I have changed the name of the module to make it
a bit clearer.