Skip to content

First commit of a mini-book on building programs #90

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
wants to merge 1 commit into from
Closed

First commit of a mini-book on building programs #90

wants to merge 1 commit into from

Conversation

arjenmarkus
Copy link
Member

Please review the text: hopefully it presents the material in a clear way. IMO, the pitfall is that it presents too much details. Suggestions for changes are welcome.

jvdp1
jvdp1 reviewed May 22, 2020
View reviewed changes
Copy link
Member

@jvdp1 jvdp1 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great text. I wish I would read it when I started with compiled languages!
I already left some comments. I will continue the revision during the weekend.

learn/building_programs.md
Comment on lines +42 to +44
program hello
write(*,*) 'Hello!'
end program hello
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All Fortran codes can be highighted with code blocks, e.g.

program hello
    write(*,*) 'Hello!'
end program hello

https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code-and-syntax-highlighting

learn/building_programs.md

But the basics are simple enough. Take the gfortran compiler, part of
the GNU compiler collection. To compile a simple program as the one
above, that consists of one source file, you run the following command:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
above, that consists of one source file, you run the following command:
above, that consists of one source file, you run the following command, assuming the source code is stored in the file "hello.f90":

learn/building_programs.md

$ gfortran -c hello.f90

(assuming the source code is stored in the file "hello.f90")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
(assuming the source code is stored in the file "hello.f90")

learn/building_programs.md

$ gfortran hello.f90

results in an executable file, "a.out" (on Linux) or "a.exe" on
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
results in an executable file, "a.out" (on Linux) or "a.exe" on
results in an executable file, "a.out" on Linux or "a.exe" on

learn/building_programs.md
the GNU compiler collection. To compile a simple program as the one
above, that consists of one source file, you run the following command:

$ gfortran -c hello.f90
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like for Fortran code, code blocks can be used to highligh shell codes.

learn/building_programs.md
directory should come consecutively.
* Many compilers allow you to specify the location for the module
intermediate files. For gfortran this is "-J", for instance:
-J../include (so that the .mod files could all appear in the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
-J../include (so that the .mod files could all appear in the
`-J../include`
(so that the .mod files could all appear in the

learn/building_programs.md
Linux and Linux-like platforms. On Windows the extension ".lib" is used.

Creating your own libraries is not that complicated: you use a utility
like "ar" or (on Windows) "lib" to achieve this:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
like "ar" or (on Windows) "lib" to achieve this:
like `ar` (on Linux) or `lib` (on Windows) to achieve this:

learn/building_programs.md
$ ar r supportlib.a file1.o file2.o
$ ar r supportlib.a file3.o ...

or, using the "link" utility:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
or, using the "link" utility:
or, using the `link` utility:

learn/building_programs.md

Note:

* The command "ar" with the option "r" either creates the library (the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* The command "ar" with the option "r" either creates the library (the
* The command `ar` with the option `r` either creates the library (the

learn/building_programs.md
* The command "ar" with the option "r" either creates the library (the
name appears after the option) or adds new object files to the library
(or replaces any existing ones).
* The command "lib" will create a new library if you use specify the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* The command "lib" will create a new library if you use specify the
* The command `lib` will create a new library if you use specify the

LKedward
LKedward requested changes May 23, 2020
View reviewed changes
Copy link
Member

@LKedward LKedward left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a great tutorial, definitely the kind of thing I needed while learning.
As Jeremie points out, the Fortran code and shell commands are best put in code blocks.

Once I finish #83, it may be a good idea to break this tutorial across multiple pages within a 'book', but for now it's good!

learn/building_programs.md
layout: page
title: Building programs
permalink: /learn/build_programs
navbar: Learn
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
navbar: Learn
navbar: Learn
date: 2020-05-22
author: Arjen Markus

We can move the date and author information up to the header (it will still be displayed on site).

learn/building_programs.md
differences that may need to be documented. Some information would be
helpful.

Author: Arjen Markus
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Author: Arjen Markus

(Moved to header)

learn/building_programs.md

Author: Arjen Markus

dd. 22 may 2020
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
dd. 22 may 2020

(Moved to header)

learn/building_programs.md
Comment on lines +140 to +143
/usr/lib/gcc/x86_64-pc-cygwin/9.3.0/../../../../x86_64-pc-cygwin/bin/ld: /usr/lib/gcc/x86_64-pc-cygwin/9.3.0/../../../../lib/libcygwin.a(libcmain.o): in function `main':
/usr/src/debug/cygwin-3.1.4-1/winsup/cygwin/lib/libcmain.c:37: undefined reference to `WinMain'
/usr/src/debug/cygwin-3.1.4-1/winsup/cygwin/lib/libcmain.c:37:(.text.startup+0x7f): relocation truncated to fit: R_X86_64_PC32 against undefined symbol `WinMain'
collect2: error: ld returned 1 exit status
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/usr/lib/gcc/x86_64-pc-cygwin/9.3.0/../../../../x86_64-pc-cygwin/bin/ld: /usr/lib/gcc/x86_64-pc-cygwin/9.3.0/../../../../lib/libcygwin.a(libcmain.o): in function `main':
/usr/src/debug/cygwin-3.1.4-1/winsup/cygwin/lib/libcmain.c:37: undefined reference to `WinMain'
/usr/src/debug/cygwin-3.1.4-1/winsup/cygwin/lib/libcmain.c:37:(.text.startup+0x7f): relocation truncated to fit: R_X86_64_PC32 against undefined symbol `WinMain'
collect2: error: ld returned 1 exit status
/usr/lib/gcc/x86_64-linux-gnu/7/../../../x86_64-linux-gnu/Scrt1.o: In function `_start':
(.text+0x20): undefined reference to `main'
collect2: error: ld returned 1 exit status

A very minor nitpick: the cygwin environment results in an overly verbose message here.
Perhaps replace with that from Ubuntu which is more concise and bit simpler for a beginner.

learn/building_programs.md
* The details differ per compiler. Sometimes the "-I" option should be
followed by a space and then the name of the directory, sometimes the
directory should come consecutively.
* Many compilers allow you to specify the location for the module
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a little too ambiguous for a beginner; can you make the difference between the -I flag and the -J flag clearer.
i.e. that compilers place the .mod files in the current directory by default and that the -J flag explicitly specifies an alternative location to place them (and search for them).

learn/building_programs.md
Comment on lines +331 to +332
* As we have seen, source code that defines one or more modules, leads to
so-called "module intermediate files" (with the extension ".mod"). The
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* As we have seen, source code that defines one or more modules, leads to
so-called "module intermediate files" (with the extension ".mod"). The
* As we have seen, compiling source code that defines one or more modules, leads to
the compiler generating so-called "module intermediate files" (with the extension ".mod"). The

learn/building_programs.md
Comment on lines +13 to +17
Remark: I only included Linux and Windows as operating systems in this
tutorial, for the simple reason that I have no experience with MacOS*
in any of its guises. While MacOS* is very similar to Linux, it is the
differences that may need to be documented. Some information would be
helpful.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Remark: I only included Linux and Windows as operating systems in this
tutorial, for the simple reason that I have no experience with MacOS*
in any of its guises. While MacOS* is very similar to Linux, it is the
differences that may need to be documented. Some information would be
helpful.
Remark: this tutorial gives examples for the Windows and Linux operating systems,
however the workflow and general principles still apply to MacOS.

It would be good if someone with experience developing on MacOS is able to check the tutorial content for any significant differences, especially with libraries.
If not, then maybe we can link to a good online resource for this?

learn/building_programs.md
Comment on lines +10 to +11
Draft tutorial: Building programs
---------------------------------
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Draft tutorial: Building programs
---------------------------------

This won't be needed, the title field in the header will be rendered first as a H1 heading.

@LKedward
Copy link
Member

I don't think this needs to be changed in this pull request but the Windows-specific content is presented for Cygwin, and I wonder whether the same content can be abstracted away from this environment somehow? For this tutorial it seems that Cygwin only serves to present the same Linux workflow but on Windows. Does Windows development need a separate tutorial maybe?

I have no problem with Cygwin but:

  • readers may not be familiar with it and;
  • it is only one of multiple linux-type interfaces for Windows.

(If I need to develop on Windows I now use MSYS2 because unlike WSL and Cygwin it produces truly native Windows executables)

jvdp1
jvdp1 reviewed May 25, 2020
View reviewed changes
Copy link
Member

@jvdp1 jvdp1 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great introduction. Cherry-pick what you want/like.

learn/building_programs.md

### Static versus dynamic libraries

The above discussion is tacitly assuming that you are using so-called
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The above discussion is tacitly assuming that you are using so-called
The above discussion is tacitly assuming that you are using the so-called

learn/building_programs.md
way to change the routines incorporated in the program is by rebuilding
the program with a new version of the library.

A flexible alternative is to use so-called dynamic libraries. These
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A flexible alternative is to use so-called dynamic libraries. These
A flexible alternative is to use the so-called dynamic libraries. These

learn/building_programs.md
the program with a new version of the library.

A flexible alternative is to use so-called dynamic libraries. These
libraries remain outside the executable program and as a consequence you
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
libraries remain outside the executable program and as a consequence you
libraries remain outside the executable program and as a consequence

learn/building_programs.md

A flexible alternative is to use so-called dynamic libraries. These
libraries remain outside the executable program and as a consequence you
can replace them without rebulding the entire program. Compilers and
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
can replace them without rebulding the entire program. Compilers and
can be replaced without rebulding the entire program. Compilers and

learn/building_programs.md
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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Differently based on what? I have the feeling that something is missing in this sentence.

learn/building_programs.md
gfortran on Cygwin and Intel Fortran on Windows. In both cases
we look at the tabulation program.

### Cygwin and gfortran
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It could be good to replace Cygwin by GNU/Linux

learn/building_programs.md
* 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
so-called makefile that contains the dependencies.
so-called `Makefile` that contains the dependencies.

learn/building_programs.md

* 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 Eclipse (Photran) and Code::Blocks. They offer a graphical
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
such Eclipse (Photran) and Code::Blocks. They offer a graphical
such as Eclipse (Photran) and Code::Blocks. They offer a graphical

learn/building_programs.md
Visual Studio project files via a high-level description. They abstract
away from the compiler and platform specifics.

Here is a very simple example of a makefile as used by the make utility,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Here is a very simple example of a makefile as used by the make utility,
Here is a very simple example of a `Makefile` as used by the make utility,

learn/building_programs.md
Note: On Windows, the Intel Fortran comes with a set of _redistributable_ libraries.
These will need to be made available.

In general: use a tool like "ldd" or "dependency walker" to find out what
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In general: use a tool like "ldd" or "dependency walker" to find out what
In general: use a tool like `ldd` or `dependency walker` to find out what

@arjenmarkus
Copy link
Member Author

arjenmarkus commented May 25, 2020 via email

@arjenmarkus
Copy link
Member Author

arjenmarkus commented May 25, 2020 via email

@certik
Copy link
Member

certik commented May 25, 2020 •
edited
Loading

Just a note regarding the platform: I strongly propose that our long term goal should be to run natively on all platforms (Linux, macOS, Windows natively as well as in Cygwin and WSL, HPC, ...) using native tools where applicable. We should have some tutorial "how to get started on each platform", and how to do the basic things for each platform. That way the actual tutorial such as this PR can be written for one particular platform (Cygwin in this case) and people would know how to execute the commands on other platforms using the "how to get started on each platform" tutorial.

So I think it's perfectly fine if this tutorial sticks with Cygwin.

@LKedward LKedward mentioned this pull request May 30, 2020
Merged
@arjenmarkus
Copy link
Member Author

arjenmarkus commented Jun 3, 2020 via email

@LKedward
Copy link
Member

LKedward commented Jun 3, 2020

Thanks for the update @arjenmarkus.
Just to let you know that there is now a guide in the repository for how to use the new multi-page mini-book format. Do let me know if anything isn't clear or you need further assistance.
Looking forward to seeing your mini-book published on site.
Laurence

@arjenmarkus
Copy link
Member Author

arjenmarkus commented Jun 4, 2020 via email

@arjenmarkus
Copy link
Member Author

arjenmarkus commented Jun 5, 2020 via email

@milancurcic milancurcic mentioned this pull request Jun 5, 2020
Merged
@LKedward
Copy link
Member

LKedward commented Jun 6, 2020

Closing, superseded by #99.

@LKedward LKedward closed this Jun 6, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jvdp1 jvdp1 jvdp1 left review comments

@LKedward LKedward LKedward requested changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@arjenmarkus @LKedward @certik @jvdp1 @arjenmarkusdeltaresnl