[cfe-dev] Why not document the -isystem command line option?

[Larry Evans]

With --stdlib=libc++ and -v options during compile step, compilation
includes output:

-internal-isystem /usr/include/c++/v1

and:

clang -cc1 version 3.1 based upon LLVM 3.1svn default target
x86_64-unknown-linux-gnu
ignoring nonexistent directory "/include"
#include "..." search starts here:
#include <...> search starts here:
 /home/evansl/prog_dev/boost-svn/ro/trunk/sandbox/rw/variadic_templates
 /home/evansl/prog_dev/boost-svn/ro/trunk
 ../../..
 /usr/include/c++/v1
 /usr/local/include
 /home/evansl/download/llvm/svn/build/Debug+Asserts/bin/../lib/clang/3.1/include
 /usr/include/x86_64-linux-gnu
 /usr/include
End of search list.

OTOH, with:

 -isystem /usr/include/c++/v1

in place of:

 --stdlib=libc++

compilation produces output:

-isystem /usr/include/c++/v1

and:

clang -cc1 version 3.1 based upon LLVM 3.1svn default target
x86_64-unknown-linux-gnu
ignoring nonexistent directory "/include"
#include "..." search starts here:
#include <...> search starts here:
 /home/evansl/prog_dev/boost-svn/ro/trunk/sandbox/rw/variadic_templates
 /home/evansl/prog_dev/boost-svn/ro/trunk
 ../../..
 /usr/include/c++/v1
 /usr/lib/gcc/x86_64-linux-gnu/4.4/../../../../include/c++/4.4
 /usr/lib/gcc/x86_64-linux-gnu/4.4/../../../../include/c++/4.4/x86_64-linux-gnu
 /usr/lib/gcc/x86_64-linux-gnu/4.4/../../../../include/c++/4.4/backward
 /usr/local/include
 /home/evansl/download/llvm/svn/build/Debug+Asserts/bin/../lib/clang/3.1/include
 /usr/include/x86_64-linux-gnu
 /usr/include
End of search list.

However, the output with the --help option makes no mention of -isystem.
 As it is, one has to provide a symlink from /usr/include/c++/v1 to the
libc++ include directory.

It would be simpler if the -isystem option were documented in the
--help output and then the user, after reading that,  could just
provide the appropriate -isystem argument to point to the libc++
include directory.

In addition, in order to find the libc++ library at link time,
the following link options could be used:

  -L$(PATH.llvm.libcxx.top)/lib -lc++

where:

  PATH.llvm.libcxx.top

is the path to the top of the libcxx project.

AFAICT, the --stdlib=libc++ is just a shorthand for the -isystem
option, but any convenience this provides is short-circuited by
having to provide the symlink, which requires root access.

-regards,
Larry