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

[Eric Fiselier via cfe-dev]

I meant to put [RFC] and not [NFC] in the title. Woops :-S

On Thu, Apr 14, 2016 at 9:24 PM, Eric Fiselier <eric at efcs.ca> wrote:

> 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/0724236b/attachment.html>