Improve documentation of Makefile system

[mandli]

Some feedback recently mentioned that it would be nice to have some further documentation on the build/make system. I purpose that we have a tutorial (perhaps) and links to the current documentation on each term and perhaps get a bit more depth as well as a high level "how to use" tutorial.

[mjberger]

Here's an example I"m running into right now. I'd like to hook in the paradise library into the Makefile. Where do I put the -L and -l commands? — Marsha

…

On May 23, 2020, at 12:04 PM, Kyle Mandli ***@***.***> wrote: Some feedback recently mentioned that it would be nice to have some further documentation on the build/make system. I purpose that we have a tutorial (perhaps) and links to the current documentation on each term and perhaps get a bit more depth as well as a high level "how to use" tutorial. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#214>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAGUGCYMYEGIWRUHDUOB4M3RS7XZFANCNFSM4NIP7RJA>.

[mandli]

It unfortunately is not always clear where to put these flags as it seems to depend on the system in question's handling of libraries and paths to those libraries. Since it does not matter too much if you over specify I try and add those to both the FFLAGS (compiler flags) and LFLAGS (linker flags). If that works you can slowly remove the flags in each systematically to figure out what the build needs. In principle this all has to do with when symbols need to be resolved and when the compiler/linker needs those definitions.

[mandli]

Does anyone have an opinion about whether we should do a

1. a simple how to with some better documentation of the build system,
2. a FAQ style or
3. both?
   I am kind of thinking of both but it will be more work.

[rjleveque]

In principle I'm in favor of all of the above, in particular:

• better documentation, improving these pages:
  • http://www.clawpack.org/makefiles.html
  • http://www.clawpack.org/makefiles_library.html
  • http://www.clawpack.org/trouble.html
• Adding more FAQ pages on this and other topics
• Creating tutorials, including maybe a video devoted to this topic.

[mandli]

I was thinking that definitely improving those pages to begin with and adding the FAQ. I am also getting setup to do some short courses this summer and probably could do some video tutorials devoted to this.

[mandli]

We should probably come up with a list of tutorial video topics as well.