[cfe-dev] [libcxx][NFC] Packaging the Filesystem library

[Eric Fiselier via cfe-dev]

Hi All,

How we package the newly standardized libraries will have an affect on
users, vendors and the libc++ implementation. This email deals specifically
with filesystem the same approach will be used for all new additions,
include ASIO.

Our end goal is to package filesystem as part of the main libc++ DSO once
the implementation has matured. Until that time we plan to ship the
experimental implementation as a separate library, libc++fs.

This should be done such that:

1) There is a clear transition path from this temporary packaging strategy
to the final one. This packaging transition should be feasible for vendors
to implement. It should also be transparent for users (in regards to how
they link their code). This transition strategy must allow libc++ to
provide legacy API and ABI support.

2) It is possible to install and update the experimental filesystem
separately from a system's libc++ installation. Many vendors will not want
to ship experimental stuff as part of their base systems but this should
not prevent the use of <experimental/filesystem>. This is also important to
allowing bug fixes to be applied without having to update the base system
since such updates can take years. Once the implementation is no longer
"experimental" this is no longer a requirement.

3) The ABI stability of the main libc++ DSO must be maintained while
allowing ABI flexibility for the experimental FS symbols. This includes the
ability to remove the std::experimental::filesystem symbols eventually.

4) Linking filesystem should be transparent to the end user. If the user is
forced to manually link the filesystem library then changing these details
will result in breakage.

==========================
The Initial implementation (libc++fs)
==========================

The implementation of the filesystem TS will be provided by the libc++fs
library, separate from the main DSO. All of the symbols in this library
will be defined within the std::experimental namespace. Users of this
library should not expect ABI compatibility and vendors who guarantee such
compatibility should not ship this as part of their base system.

During this time the C++17 implementation of std::filesystem can be
provided as an
alias to std::experimental::filesystem. Users with minimal ABI concerns can
use the C++17 API immediately without worrying about transitioning later.
Vendors with ABI concerns can choose only to ship <experimental/filesystem>
and not <filesystem>.

Goal #4 can be achieved with the use of linker scripts (except on OS X).
During this time the default libc++ build will create libc++.so as a linker
script that automatically links to libc++fs. Users are free to disable this
behavior. (Suggestions are welcome on how to achieve goal #4 on OS X!).

By default libc++fs will build as a static library (except on OS X).

==========================
The Transition into the libc++ DSO
==========================

Once libc++fs has matured the symbols will be moved into the main DSO and
out of the experimental namespace. At this point the <filesystem> ABI will
be considered stable and we can
begin to depreciate <experimental/filesystem>. By default libc++ will no
longer build libc++fs.

During this transition the implementation of <experimental/filesystem> will
be removed and changed to simply refer to <filesystem> using a namespace
alias. No definitions for experimental symbols will be provided. This
provides legacy API but with a different ABI. Programs compiled against
libc++fs are not ABI compatible with newer programs that use filesystem.

Some vendors, such as Apple, will continue to require libc++fs in order to
package applications for older system. I believe it should be sufficient to
provide libc++fs with a new ABI by using the same object files used to
build the libc++ DSO. This means that libc++fs will contain the definitions
in namespace std::filesystem instead of std::experimental::filesystem. Note
that the new libc++fs ABI would still be compatible with older libc++ DSO's.

=========
Conclusion
=========

I hope I have been able to explain the plan and the rational for it.
Please ask for clarification if I've confused.
Any and all feedback is appreciated.

/Eric
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20160414/b3ff0c73/attachment.html>