Tutorial: building compiled programs

[LKedward]

As discussed on fortran-lang mailing list, this will cover compiling, linking and libraries.

Assigned: @arjenmarkus

[arjenmarkus]

I took the opportunity of a couple of hours during a lazy evening to sit down and write a quick-and-dirty document. No Markdown mark-up, just plain text. It is just the start, but it should illustrate what I am thinking of. Of course there are plenty of tools to help with building a program, but I think it is also important to understand what is going on when you build a program.

The document is very much work-in-progress, so have a look and et me know whether this is useful or not.

building_programs.txt

[certik]

@arjenmarkus I think this looks great and I would like to have it in our Documentation section somewhere. @milancurcic, @LKedward where do you think would be the best place?

[milancurcic]

I love this. I think this is the kind of style we should take for tutorials.

I think it would work well as a self-contained "book" (as described in fortran-lang/webpage#69) on building and linking, and we can link to it from the quickstart tutorial (/learn page).

It will be straightforward to convert it to Markdown.

[LKedward]

Looks great, thanks @arjenmarkus.

[arjenmarkus]

Well, that is encouraging :). Regards, Arjen Op vr 15 mei 2020 om 22:08 schreef Laurence Kedward < notifications@github.com>:

…

Looks great, thanks @arjenmarkus <https://github.com/arjenmarkus>. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#77 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAN6YRZGPFQNWV62M4QGT6LRRWONJANCNFSM4NBUJL7Q> .

[jvdp1]

@arjenmarkus Thank you for this manuscript. I really like the style.
It would be indeed easy to convert it to Markdown. We could help with the conversion when it will submitted to a PR.

[arjenmarkus]

Thanks - I am always a trifle uncertain about the precise formatting or the dialect. Of course, so far the formatting requirements are very basic - and I intend to keep it that way. Regards, Arjen Op za 16 mei 2020 om 08:35 schreef Jeremie Vandenplas < notifications@github.com>:

…

@arjenmarkus <https://github.com/arjenmarkus> Thank you for this manuscript. I really like the style. It would be indeed easy to convert it to Markdown. We could help with the conversion when it will submitted to a PR. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#77 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAN6YRYQGAVJTKVTXMZHPMDRRYX3NANCNFSM4NBUJL7Q> .

[arjenmarkus]

Short update: I have almost completed the draft of the tutorial I have in mind. A rather tricky problem: make sure the _necessary_ details are presented in a clear and structured way. It is easy enough to structure the text and it is easy enough to describe all the details. But the challenge is: only what is necessary in a structured way :). Putting in the Markdown formatting was not a big issue, butI will probably need some assistance with the next step - the pull request. Regards, Arjen Op za 16 mei 2020 om 20:32 schreef Arjen Markus <arjen.markus895@gmail.com>:

…

Thanks - I am always a trifle uncertain about the precise formatting or the dialect. Of course, so far the formatting requirements are very basic - and I intend to keep it that way. Regards, Arjen Op za 16 mei 2020 om 08:35 schreef Jeremie Vandenplas < ***@***.***>: > @arjenmarkus <https://github.com/arjenmarkus> Thank you for this > manuscript. I really like the style. > It would be indeed easy to convert it to Markdown. We could help with the > conversion when it will submitted to a PR. > > — > You are receiving this because you were mentioned. > Reply to this email directly, view it on GitHub > <#77 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AAN6YRYQGAVJTKVTXMZHPMDRRYX3NANCNFSM4NBUJL7Q> > . >

[LKedward]

Thanks for the update @arjenmarkus.
Regarding the next step, I'm happy to provide guidance on putting together the PR or otherwise to submit the PR myself on your behalf.

[arjenmarkus]

Hi Laurence, okay, I have finished the draft, converted it to Markdown and I have cloned the website on my machine. I can simply add the file in the subdirectory "learn", but I suppose I also need to add the header, like from the index: --- layout: page title: Quickstart Fortran permalink: /learn/ navbar: Learn --- but what to fill in? Also: for now I have added a link to CC-BY, but is that the sort of license we want to use for these mini-books? Or do we use LGPL or ...? Regards, Arjen . Op di 19 mei 2020 om 09:35 schreef Laurence Kedward < notifications@github.com>:

…

Thanks for the update @arjenmarkus <https://github.com/arjenmarkus>. Regarding the next step, I'm happy to provide guidance on putting together the PR or otherwise to submit the PR myself on your behalf. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#77 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAN6YR3FKPEDIEZ32WDH6R3RSIZETANCNFSM4NBUJL7Q> .

[LKedward]

Hi @arjenmarkus,
Sounds good. Regarding the header, you only need to change the title field to the title of your tutorial
and the permalink field to something like permalink: /learn/building_programs - this will cause the web address of your tutorial to be https://fortran-lang.org/learn/building_programs. The ending after /learn/ just needs to be a short descriptive string for your tutorial. The other fields (layout, navbar) can be kept the same as in the index file.

I'm not sure if we are using a different license for the tutorial content - the website source is currently licensed under MIT, but it may be a good idea to license the tutorials under one of the CC-BY licenses. As the author and copyright holder, the licensing of the tutorial content is ultimately your choice - but it would be good to agree a license for all tutorial and similar content on fortran-lang.org. What are your thoughts @milancurcic and @certik ?

[certik]

I suggest to use an MIT license by default for such books. Consistent with other materials here. Unless the author specifically objects, in which case we can discuss on a case by case basis.

…

On Fri, May 22, 2020, at 8:14 AM, arjenmarkus wrote: Hi Laurence, okay, I have finished the draft, converted it to Markdown and I have cloned the website on my machine. I can simply add the file in the subdirectory "learn", but I suppose I also need to add the header, like from the index: --- layout: page title: Quickstart Fortran permalink: /learn/ navbar: Learn --- but what to fill in? Also: for now I have added a link to CC-BY, but is that the sort of license we want to use for these mini-books? Or do we use LGPL or ...? Regards, Arjen . Op di 19 mei 2020 om 09:35 schreef Laurence Kedward < ***@***.***>: > Thanks for the update @arjenmarkus <https://github.com/arjenmarkus>. > Regarding the next step, I'm happy to provide guidance on putting together > the PR or otherwise to submit the PR myself on your behalf. > > — > You are receiving this because you were mentioned. > Reply to this email directly, view it on GitHub > <#77 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AAN6YR3FKPEDIEZ32WDH6R3RSIZETANCNFSM4NBUJL7Q> > . > — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#77 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAFAWBIDBGGX23I6ZUPBZTRS2CELANCNFSM4NBUJL7Q>.

[LKedward]

I suggest to use an MIT license by default for such books. Consistent with other materials here. Unless the author specifically objects, in which case we can discuss on a case by case basis.

I agree with preferring consistency, but MIT is strictly a software license - I believe the general copyright equivalent is CC-BY which simply requires attribution like MIT.

[certik]

I am not an expert on the CC licenses, I know some of them are not open source so we have to be very careful to pick the right one. What does Rust use for their documentation?

…

On Fri, May 22, 2020, at 8:34 AM, Laurence Kedward wrote: > I suggest to use an MIT license by default for such books. Consistent with other materials here. Unless the author specifically objects, in which case we can discuss on a case by case basis. I agree with preferring consistency, but MIT is strictly a software license - I believe the general copyright equivalent is CC-BY which simply requires attribution like MIT. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#77 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAFAWAWTD7KUYWDJZRTMETRS2EQ5ANCNFSM4NBUJL7Q>.

[certik]

P.S. I view documentation as code: it's written in Markdown, which literally is a source code that gets parsed and compiled to the final form, whether html or pdf. Also one can then copy and paste example code from the documentation into user projects without problem. So I've always used MIT for documentation. But I am not opposed to other options.

…

On Fri, May 22, 2020, at 8:38 AM, Ondřej Čertík wrote: I am not an expert on the CC licenses, I know some of them are not open source so we have to be very careful to pick the right one. What does Rust use for their documentation? On Fri, May 22, 2020, at 8:34 AM, Laurence Kedward wrote: > > > > I suggest to use an MIT license by default for such books. Consistent with other materials here. Unless the author specifically objects, in which case we can discuss on a case by case basis. > > I agree with preferring consistency, but MIT is strictly a software > license - I believe the general copyright equivalent is CC-BY which > simply requires attribution like MIT. > > — > You are receiving this because you were mentioned. > Reply to this email directly, view it on GitHub > <#77 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAFAWAWTD7KUYWDJZRTMETRS2EQ5ANCNFSM4NBUJL7Q>. >