[Documentation] Help understanding the build system - adding to wiki

[epsilon-0]

I'm trying to get a clear idea of how the build system works and thankfully due to using Makefiles, it is a lot clearer than autotools and other cancerous build systems. Thanks a lot for that :heart:

So I made a preliminary page in the wiki to keep notes about the build system - https://github.com/xianyi/OpenBLAS/wiki/WIP---Build-system-overview-(community-made)
I am hoping more experienced people can give their input there and make it a lot more complete. I only started understanding this library today so my work is very rudimentary but I feel like having that wiki page would be tremendously helpful for A LOT of people.

Thanks, Aisha

[martin-frbg]

The makefiles are a bit messy as there is some recursion involved, but generally you will find all configurable options with a short description in Makefile.rule. Makefile.prebuild creates the tools for detecting the cpu model and related settings and runs them, sending their output to Makefile.conf (or Makefile.kernel.conf in DYNAMIC_ARCH builds) and config.h. Once the cpu architecture is known, the corresponding Makefile.xxx (e.g. Makefile.power) is included by Makefile.system for architecture-specific settings. Makefile.tail contains settings and targets that are common between all the subdirectory Makefiles e.g. interface/Makefile, kernel/Makefile and a few others.

[epsilon-0]

@martin-frbg Haha, a small amount of mess is fine. I'd be happy to help make it a bit more organized :smile_cat: . I'm hoping to maintain this package for Gentoo Linux, and it needs me to have a clear picture of the build system.

Hopefully, creating the wiki page is not considered a bad idea. One of the things that I wanted to do was to allow the setting of variables without needing Makefile.prebuild to actually compile code, as this breaks things for cross compile. I know that there is a cross compilation guide in the README but I want to make it a bit more clear. Like, what is the use of the HOSTCC variable? Ideally if we are doing cross compile, we shouldn't need the HOSTCC at all. I'm not saying it is wrong, but it would be nice to clarify these points and give simple reasons.

I'll do some reading of the Makefiles and try to add the information to the wiki. Hopefully others can do that as well (and correct any mistakes I've made)

[martin-frbg]

Having a wiki page for this is probably not a bad idea, though perhaps it would make sense to start with a big disclaimer that it is not "official"/verified developer documentation but personal notes you make as you try to understand the layout. Or just refrain from documenting anything there while it is still unclear to you. In particular having things with multiple question marks or even a "why do we need this" only serve to reflect poorly on the project unless it is obvious that it was not produced by someone familiar with the code. While it is the spirit of a wiki to allow gradual improvement by input from multiple contributors, please do not try to force me or anyone else to put time into this immediately.

HOSTCC is needed precisely for compiling the getarch tools when your CC is set to the crosscompiler, though the getarch output may be predetermined information rather than anything actually probed in that case. Getting rid of compiled tools is problematic when you need low-level access to system functions (e.g. cpuid), and when you cannot be sure that everybody has the interpreter for your particular favorite script language already installed. (It is/was bad enough with the perl scripts, e.g requiring perl preinstalled on Windows and expecting particular perl modules to be available on embedded systems with tiny disk space)

[epsilon-0]

Having a wiki page for this is probably not a bad idea, though perhaps it would make sense to start with a big disclaimer that it is not "official"/verified developer documentation but personal notes you make as you try to understand the layout. Or just refrain from documenting anything there while it is still unclear to you. In particular having things with multiple question marks or even a "why do we need this" only serve to reflect poorly on the project unless it is obvious that it was not produced by someone familiar with the code. While it is the spirit of a wiki to allow gradual improvement by input from multiple contributors, please do not try to force me or anyone else to put time into this immediately.

Oh not at all, I'm not forcing anyone to do this. I'm creating it for myself and hoping it will help others too.
You are right that this should be documented as made by someone who is not a developer and is still a WIP.
I've added the disclaimer in bold right at the top, changed the page title to (community made) and made it perfectly clear that it is not an official documentation.
I hope that is fine?

HOSTCC is needed precisely for compiling the getarch tools when your CC is set to the crosscompiler, though the getarch output may be predetermined information rather than anything actually probed in that case. Getting rid of compiled tools is problematic when you need low-level access to system functions (e.g. cpuid), and when you cannot be sure that everybody has the interpreter for your particular favorite script language already installed. (It is/was bad enough with the perl scripts, e.g requiring perl preinstalled on Windows and expecting particular perl modules to be available on embedded systems with tiny disk space)

In fact, knowing that HOSTCC is used as a replacement for the scripting tools, has already helped a lot!! I just got the cross compilation to work upto a large extent on Gentoo's packaging system, so this is really informative.

Thanks a lot for your input. I will try to understand more and make it clearer.

[brada4]

I'd like to know what optimisations are lost with DYNAMIC_ARCH. With references.

[epsilon-0]

I'd like to know what optimisations are lost with DYNAMIC_ARCH. With references.

Whoops, seems like I made a mistake. I just came across the old thread - https://github.com/xianyi/OpenBLAS/issues/1779, which was talking about this. I've updated the wiki, hope that is ok?

[martin-frbg]

Not sure how you got that from #1779 when the entire point of DYNAMIC_ARCH is to provide optimisations for multiple cpu models in a single library. Only when there is no specific support for a given (outdated) model in the library would you get a fallback to the closest supported one - that was a trade-off specifically for the x86/x86_64 architecture to keep compilation time and library size reasonable, and you can still get the entire range by requesting DYNAMIC_OLDER in addition.

[martin-frbg]

Some more things - "TARGET" is not only used for DYNAMIC_ARCH, but anytime the cpu to build for can or should not be autodetected (building for a specific other computer, building with a cpu too new to be recognized), and TARGET_CORE is what gets used internally for interating over the cpu models to build in DYNAMIC_ARCH mode. HOSTCC is only needed when cross-compiling. QUAD_PRECISION is not only "experimental" but largely unimplemented (as stated in Makefile.rule - the original author of GotoBLAS added several such stubs for things he apparently thought might be worthwile to implement later. The BUILD_SINGLE etc that you have decorated with question marks are new options from (the ill-fated) 0.3.11 release that support building only the BLAS/LAPACK functions that are relevant for the corresponding variable type.

[brada4]

I added description of interactions between TARGET and DYNAMIC_ARCH, should be mentioned somewhere that normally local-only build is done by invoking make or gmake, or use downstream packages. It is much better to direct readers to least resistance options than to drag them through all possibilities of failed build....