CGAL: Which headers to include

Question

What is the standard workflow to figure out which headers are needed to make the program compile?

Take the following simple example

#include <iostream>
int main() {
  std::cout << CGAL::square(0.002) << '\n';
  return 0;
}

The function square is defined in Algebraic_foundations/include/CGAL/number_utils.h.

Question 1: Why is it not enough to just #include <CGAL/number_utils.h>?

I was made aware that #include <CGAL/basic.h> makes the program compile. I guess one can use a more fine-grained file inclusion and looking in basic.h I found out that #include <CGAL/number_type_basic.h> is enough.

Question 2: Does using a finer-grained file inclusion decrease compilation time (less text in compilation unit?) but executable/object files will not differ as compilers remove the excess code from unneeded inclusions?

Question 3: Is there another rationale why one would use finer inclusions? Some kind of style guide? Or is it even good practice to include a high-level header to make it safe against changes in low-level code?

Question 4: What kind of high-level headers are there in CGAL? Is there one for the whole library? How is the connection regarding all the different packages? Is there one for each package?

Question 5: If it is good practice to include middle- to lower-level header files then what is the standard workflow to figure out which headers are needed, e.g. for the square function in the above mentioned example?

Answer 1

Almost all reference manual pages such as this one of the class Triangulation_2 give as very first information which header file to include. All higher level data structures are parameterized with a geometric traits class for which they in most cases pass a kernel, e.g., the Exact_predicates_inexact_constructions_kernel, which again states what header to include. The latter will define number types which include all the infrastructure. Note that CGAL/basic.h is not documented.