made config header optional

[TysonRayJones]

• renamed config.h to quest_config.h and made it an optional include which demands no macros are pre-defined, as per the discussions in Fix for quest.h generation #645
• added a COMPILE_HIP macro merely for book-keeping
• added TODO for 'installing' in compile.md doc
• explained quest_config.h in compile.md doc
• corrected a typo in docs/README.md

[TysonRayJones]

@otbrown What do you think of this? Have I accidentally broken installation? 😅

EDIT: woops I've unhelpfully broken everything - I'll re-ping when patched but feel free to comment on the proposed changes generally!

[TysonRayJones]

Ahh I had colossally brainfarted! Macro FLOAT_PRECISION must always be known by the user's importing code since it informs the qreal and qcomp types and ergo almost every QuEST signature! 😓 Compilation with the non-default FLOAT_PRECISION=2 now will fail.

Perhaps there remains a way to handle it specially so that quest_config.h need not always be included hmm

[otbrown]

Ah bugger 😅

I was going to suggest making precision.h another CMake config'd file, but then that would permanently break make only building, sooooo, what about:

Using CMake configure_file: precision_config.h.in -> precision_config.h, which just contains #define FLOAT_PRECISION X.

Then in precision.h:

#ifndef FLOAT_PRECISION
#include "precision_config.h"
#endif

CMake users get one extra include file in the includes directory, but otherwise everything looks as it does now. Make users must define FLOAT_PRECISION when compiling either QuEST or onwards codes, or otherwise create precision_config.h?

Edit to add:
Make is really just bash with airs, so one could actually create precision_config.h using echo in the makefile to be fair!

[TysonRayJones]

That configure_file hackery is clever but I worry it's vomit-inducing and prone to cause future confusions.

I really like your idea to just make the otherwise-CMake-made file directly in the makefile or the manual bash script though! That's a much simpler and more elegant hack that's necessary only in the non-primary build method. So "main" CMake users are never exposed to mischief.

I'll probably be slow in getting to this since it's a low-priority and I want to be super cautious I do it in a forward-maintainable way (in case FLOAT_PRECISION turns out not to be the only critical install-time macro)

[TysonRayJones]

Notes on refactor (which I'll hopefully find time to do this weekend 🤞 ):

• The modes.h, precision.h and config.h headers are poorly distinguished and confusing when studied in the context of installation. Perhaps these should be merged into one CMake-generated file.
• There should be no ifndef MACRO; define MACRO invocations outside of config.h since this could introduce a bug when installing QuEST if the header include order changes.
• Somehow config.h should detect that the CMake-saved macro definitions are consistent with those superfluously re-passed by the user (though this detection must not be tripped up when not installing QuEST)
• The name config.h may be imprecise; consider that debug.h contains user-facing functions for configuring the QuEST runtime. Perhaps it should be renamed to compile_config.h or preconfig.h?
• Should macros INCLUDE_DEPRECATED_FUNCTIONS and DISABLE_DEPRECATION_WARNINGS (currently in modes.h) also be CMake-saved, for consistency? Note this restricts them from being toggled on-and-off post-installation, which is a silly/unimportant use-case. It might also break how the v3 test utilities disable repeated deprecation warnings etc.
• Is it possible/advisable to never pass compile-time macros to any source file, but instead have config.h contain them as generated from config.h.in?

[TysonRayJones]

superseded by #685