Hi All,
I heartily agree with Adrian - the documentation for cmake needs to be
*vastly* improved, and also centralized if at all possible. I ran into
headaches with cmake documentation recently, details below.
On Mon, Apr 5, 2021 at 12:50 PM David A Case <david.case.rutgers.edu> wrote:
>
> We are using the wiki rather than a --help option for this purpose. Two
> pages are good starting points:
>
> https://ambermd.org/pmwiki/pmwiki.php/Main/CMake-Quick-Start
>
> is a good overview. It has an FAQ with answers to questions such as
> "How can I build only one specific program?" or "I want to see what commands
> make is actually executing!"
>
> Also very helpful is this one:
>
> https://ambermd.org/pmwiki/pmwiki.php/Main/CMake-Common-Options
These pages are good, but they are also incomplete. Recently, I was
trying to figure out how to specify an external NetCDF library (with
configure, accomplished using '--with-netcdf=$netcdf_home'). There is
no specific option for cmake given, but the text at the bottom of the
"Common Options" wiki page indicates (talking about the old configure
flag -netcdfstatic):
"-netcdfstatic -- Just change NETCDF_LIBRARIES_C,
NETCDF_LIBRARIES_F77, and NETCDF_LIBRARIES_F90 to point to static
libraries."
This actually **does not work** for specifying an external NetCDF.
Cmake will complain about "Failed to find NetCDF interface for
F77/F90". The manual has a few additional breadcrumbs (in 2.2.3): it
mentions specifying the location of parallel NetCDF:
```
For example, if you saw this output:
-- Could NOT find PnetCDF_C (missing: PnetCDF_C_LIBRARY PnetCDF_C_INCLUDE_DIR)
you could help CMake find the library with the following command:
cmake <path to source> -DPnetCDF_C_LIBRARY=<path to libpnetcdf.so> \
-DPnetCDF_C_INCLUDE_DIR=<path to folder containing pnetcdf.h>
```
Using this as a hint, and diving into the cmake scripts for the actual
variable names, I figured out I could specify an external NetCDF file
via the CMAKE variables:
-DNetCDF_LIBRARIES_C=$netcdf_home/lib/libnetcdf.a \
-DNetCDF_INCLUDES=$netcdf_home/include \
-DNetCDF_LIBRARIES_F77=$netcdf_home/lib/libnetcdff.a \
-DNetCDF_LIBRARIES_F90=$netcdf_home/lib/libnetcdff.a \
-DNetCDF_INCLUDES_F90=$netcdf_home/include \
-DNetCDF_INCLUDES_F77=$netcdf_home/include
This took some dedicated sleuthing on my part, and I'm a long-time
developer. I don't think users shouldn't have to jump through these
hoops.
> p.p.s. Note that the current output of configure --help is 54 lines long,
> and that of configure --full-help (which is needed to get help for any but
> the most elementary subjects) is 154 lines.
Be that as it may, whenever I had a question on how to build amber, 99
times out of 100 I could do './configure --full-help | less` and have
a one-stop shop of options and what they do, and then figure out what
I needed to set. So I very much second Adrian's suggestion that there
be a single location where all configurable cmake options are listed.
Whether that is a wiki page, a page in the manual, or some sort of
onboard help program I don't particularly care. I just don't want to
have to dive all over wiki pages, then the manual, then into the guts
of cmake every time I want to change a default. Also, having a single
source will make keeping that documentation up-to-date feasible.
-Dan
>
> This shows you how to ask for the most common changes, such as how to skip
> certain builds, change what libraries are used, change compiler flags, etc.
>
> If you look at the table of contents at the left of any of these pages, you
> will see several other CMake related pages.
>
> For everyone: please note that these are wiki pages! If there is something
> that is unclear, or is missing, please edit things to make them better.
>
> ...hope this helps....dac
>
> p.s. the links above are printed out at the very beginning of every CMake
> run. See also Section 2.2 of the Amber Reference Manual.
>
> p.p.s. Note that the current output of configure --help is 54 lines long,
> and that of configure --full-help (which is needed to get help for any but
> the most elementary subjects) is 154 lines. Also note that things like
> compiler info in the help output are 4-5 years out of date, and other pieces
> of information in the current help output are also wrong or misleading. So,
> in my view, using a wiki is a better way to make things easy to read, and
> to keep them up to date.
>
> Finally, the current configure help doesn't even try to answer Adrian's
> question about "building some things but not others". The answer for the
> legacy configure system is this "find the relevant Makefile, and edit it."
> For CMake, you add an option to your run_cmake script.
>
> _______________________________________________
> AMBER-Developers mailing list
> AMBER-Developers.ambermd.org
> http://lists.ambermd.org/mailman/listinfo/amber-developers
_______________________________________________
AMBER-Developers mailing list
AMBER-Developers.ambermd.org
http://lists.ambermd.org/mailman/listinfo/amber-developers
Received on Mon Apr 05 2021 - 12:00:03 PDT
