From b9d38eadae2fd9d933abb20893d2a3f822b0210e Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Tue, 4 Feb 2020 09:01:36 +0200
Subject: Add note to manual on specifying search paths in compiler mode

---
 doc/manual.cli             | 13 +++++++++++++
 libbuild2/cc/common.cxx    |  2 ++
 libbuild2/cc/pkgconfig.cxx |  4 +++-
 3 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/doc/manual.cli b/doc/manual.cli
index bd06809..525d74e 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -1732,6 +1732,19 @@ will appear last on the command lines. For example:
 $ b configure config.cxx=\"g++ -m32\"
 \
 
+The compiler mode options are also the correct place to specify
+\i{system-like} header (\c{-I}) and library (\c{-L}, \c{/LIBPATH}) search
+paths. Where by system-like we mean common installation directories like
+\c{/usr/include} or \c{/usr/local/lib} which may contain older versions of the
+libraries we are trying to build and/or use. By specifying these paths as part
+of the mode options (as opposed to \c{config.*.poptions} and
+\c{config.*.loptions}) we make sure they will be considered last, similar to
+the compiler's build-in search paths. For example:
+
+\
+$ b configure config.cxx=\"g++ -L/opt/install\"
+\
+
 |
 
 We can also configure out of source builds of our projects. In this case,
diff --git a/libbuild2/cc/common.cxx b/libbuild2/cc/common.cxx
index b949c2b..6030954 100644
--- a/libbuild2/cc/common.cxx
+++ b/libbuild2/cc/common.cxx
@@ -1040,6 +1040,8 @@ namespace build2
           gcc_extract_library_search_dirs (v, r);
       };
 
+      // Note that the compiler mode options are in sys_lib_dirs.
+      //
       if (auto l = bs[c_loptions]) extract (*l, c_loptions);
       if (auto l = bs[x_loptions]) extract (*l, x_loptions);
 
diff --git a/libbuild2/cc/pkgconfig.cxx b/libbuild2/cc/pkgconfig.cxx
index 3e25167..5d5a43c 100644
--- a/libbuild2/cc/pkgconfig.cxx
+++ b/libbuild2/cc/pkgconfig.cxx
@@ -74,7 +74,9 @@ namespace build2
 #ifndef BUILD2_BOOTSTRAP
 
   // Load package information from a .pc file. Filter out the -I/-L options
-  // that refer to system directories.
+  // that refer to system directories. This makes sure all the system search
+  // directories are "pushed" to the back which minimizes the chances of
+  // picking up wrong (e.g., old installed version) header/library.
   //
   // Note that the prerequisite package .pc files search order is as follows:
   //
-- 
cgit v1.1