Skip to content

Tutorial: building compiled programs #77

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
LKedward opened this issue May 15, 2020 · 29 comments
Closed

Tutorial: building compiled programs #77

LKedward opened this issue May 15, 2020 · 29 comments

Comments

@LKedward
Copy link
Member

LKedward commented May 15, 2020 •
edited
Loading

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

Assigned: @arjenmarkus
@arjenmarkus
Copy link
Member

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
Copy link
Member

certik commented May 15, 2020

@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
Copy link
Member

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
Copy link
Member Author

Looks great, thanks @arjenmarkus.

@arjenmarkus
Copy link
Member

arjenmarkus commented May 15, 2020 via email

@jvdp1
Copy link
Member

jvdp1 commented May 16, 2020

@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
Copy link
Member

arjenmarkus commented May 16, 2020 via email

@arjenmarkus
Copy link
Member

arjenmarkus commented May 19, 2020 via email

@LKedward
Copy link
Member Author

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
Copy link
Member

arjenmarkus commented May 22, 2020 via email

@LKedward
Copy link
Member Author

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
Copy link
Member

certik commented May 22, 2020 via email

@LKedward
Copy link
Member Author

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
Copy link
Member

certik commented May 22, 2020 via email

@certik
Copy link
Member

certik commented May 22, 2020 via email

@LKedward
Copy link
Member Author

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.

Ah okay, good point - I'm no expert either.

What does Rust use for their documentation?

It appears to be under the same license as Rust itself which is MIT/Apache2.

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.

This makes sense to me; I'm happy to keep with MIT for consistency then 👍

@arjenmarkus
Copy link
Member

arjenmarkus commented May 22, 2020 via email

@certik
Copy link
Member

certik commented May 22, 2020

Ok then, let's stick to MIT then.

@arjenmarkus
Copy link
Member

arjenmarkus commented May 22, 2020 via email

@arjenmarkus
Copy link
Member

arjenmarkus commented May 22, 2020 via email

@certik certik mentioned this issue May 22, 2020
Closed
@certik
Copy link
Member

certik commented May 22, 2020

@arjenmarkus did you figure it out?

I struggle with Jekyll too. See also #89.

@milancurcic
Copy link
Member

@arjenmarkus we can also build a live preview from a pull request. Here's what you need to do:

  1. Fork this repository
  2. Clone your fork (not this repo), that would be https://github.com/arjenmarkus/fortran-lang.org
  3. Add your content locally, commit it, then push to your repo on GitHub.
  4. When you navigate back to this repo, there will be a button suggesting you to open a pull request
  5. In pull request dialog, check the box that says "allow edits from reviewers" (or similar).

and we can make sure it previews correctly from there.

@arjenmarkus
Copy link
Member

arjenmarkus commented May 22, 2020 via email

@arjenmarkus
Copy link
Member

arjenmarkus commented May 22, 2020 via email

@milancurcic
Copy link
Member

Almost there. It looks like you created a pull request in your own repository (arjenmarkus/fortran-lang.org).

Instead, create a pull request in this repository (fortran-lang/fortran-lang.org) by navigating to its home page and clicking on the "New pull request" button.

I don't know if this matters, but I also see that your fortran-lang.org repository doesn't appear as a fork. Did you create it by clicking the "Fork" button on this repository?

@arjenmarkus
Copy link
Member

arjenmarkus commented May 22, 2020 via email

@arjenmarkus
Copy link
Member

arjenmarkus commented May 22, 2020 via email

@milancurcic
Copy link
Member

@arjenmarkus Yes, that worked! Thank you! I will review it in detail over the weekend.

@LKedward
Copy link
Member Author

Closing, completed by #99.

@milancurcic milancurcic mentioned this issue Jun 20, 2020
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@certik @arjenmarkus @milancurcic @jvdp1 @LKedward