Implement <filesystem>

This patch implements the <filesystem> header and uses that
to provide <experimental/filesystem>.

Unlike other standard headers, the symbols needed for <filesystem>
have not yet been placed in libc++.so. Instead they live in the
new libc++fs.a library. Users of filesystem are required to link this
library. (Also note that libc++experimental no longer contains the
definition of <experimental/filesystem>, which now requires linking libc++fs).

The reason for keeping <filesystem> out of the dylib for now is that
it's still somewhat experimental, and the possibility of requiring an
ABI breaking change is very real. In the future the symbols will likely
be moved into the dylib, or the dylib will be made to link libc++fs automagically).

Note that moving the symbols out of libc++experimental may break user builds
until they update to -lc++fs. This should be OK, because the experimental
library provides no stability guarantees. However, I plan on looking into
ways we can force libc++experimental to automagically link libc++fs.

In order to use a single implementation and set of tests for <filesystem>, it
has been placed in a special `__fs` namespace. This namespace is inline in
C++17 onward, but not before that. As such implementation is available
in C++11 onward, but no filesystem namespace is present "directly", and
as such name conflicts shouldn't occur in C++11 or C++14.

git-svn-id: https://llvm.org/svn/llvm-project/libcxx/trunk@338093 91177308-0d34-0410-b5e6-96231b3b80d8

docs/BuildingLibcxx.rst

@@ -242,11 +242,15 @@ libc++experimental Specific Options
 
 .. option:: LIBCXX_ENABLE_FILESYSTEM:BOOL
 
-  **Default**: ``LIBCXX_ENABLE_EXPERIMENTAL_LIBRARY``
+  **Default**: ``ON``
 
-  Build filesystem as part of libc++experimental.a. This allows filesystem
-  to be disabled without turning off the entire experimental library.
+  Build filesystem as a standalone library libc++fs.a.
 
+.. option:: LIBCXX_INSTALL_FILESYSTEM_LIBRARY:BOOL
+
+  **Default**: ``LIBCXX_ENABLE_FILESYSTEM AND LIBCXX_INSTALL_LIBRARY``
+
+  Install libc++fs.a alongside libc++.
 
 .. _ABI Library Specific Options:
 

docs/UsingLibcxx.rst

@@ -49,6 +49,24 @@ An example of using ``LD_LIBRARY_PATH``:
   $ export LD_LIBRARY_PATH=<libcxx-install-prefix>/lib
   $ ./a.out # Searches for libc++ along LD_LIBRARY_PATH
 
+
+Using ``<filesystem>`` and libc++fs
+====================================
+
+Libc++ provides the implementation of the filesystem library in a separate
+library. Users of ``<filesystem>`` and ``<experimental/filesystem>`` are
+required to link ``-lc++fs``.
+
+.. note::
+  Prior to libc++ 7.0, users of ``<experimental/filesystem>`` were required
+  to link libc++experimental.
+
+.. warning::
+  The Filesystem library is still experimental in nature. As such normal
+  guarantees about ABI stability and backwards compatibility do not yet apply
+  to it. In the future, this restriction will be removed.
+
+
 Using libc++experimental and ``<experimental/...>``
 =====================================================
 
@@ -65,6 +83,9 @@ installed. For information on building libc++experimental from source see
 :ref:`Building Libc++ <build instructions>` and
 :ref:`libc++experimental CMake Options <libc++experimental options>`.
 
+Note that as of libc++ 7.0 using the ``<experimental/filesystem>`` requires linking
+libc++fs instead of libc++experimental.
+
 Also see the `Experimental Library Implementation Status <http://libcxx.llvm.org/ts1z_status.html>`__
 page.