* we shouldn't have to worry about properly escaping or roundtripping includes between JSON and... literally anything else

Right, having to worry about escape is hideous. MSVC toolset, for example, uses the fields 'angledHeader' and 'quotedHeader'.

Using the logical header names (as they would appear in C++-level source) allows relocation, in additional to distributed builds without worrying about how the host filesystem is laid out.

-- Gaby

From: SG15 <sg15-bounces_at_[hidden]> On Behalf Of Isabella Muerte via SG15
Sent: Tuesday, May 11, 2021 12:49 PM
To: sg15_at_[hidden]
Cc: Isabella Muerte <imuerte_at_[hidden]>
Subject: Re: [SG15] Scandeps format post-P1689R3 discussion

On Tue, May 11, 2021, at 12:15, Ben Boeckel via SG15 wrote:
Hi,

After discussing with some implementers about real-world usage of the r3
format. In these discussions the following things have been considered:

# Dropping the `inputs`, `outputs`, and `depends` arrays

These fields are intended to capture the dependency information of the
scanning step itself. The intended replacement is the normal dependency
mechanisms offered by compilers (be it `/showIncludes`, `-M`, or other
possible mechanisms). These are really only of use to the build tool
itself to know when to recompile the file, so putting it into the file
format itself is unnecessary.


I'm very much against relying on 'existing' mechanisms as none of them are uniform between implementations, nor even between locale implementations. I would be fine with having multiple formats, or even spinning these arrays out into their own file, but a uniform format for these is desperately needed, especially in multi-language repositories where C++ code might be wrapped for use in something like Node, Ruby, Python, etc. C++ needs to be usable outside of a purely C++ environment, and making other languages struggle when they can just call `cargo build` or even just `rustc <entrypoint-file>` instead is going to be a detriment.

In addition, there are two other reasons that have come up to at least
consider changing these keys:

  - the `depends` array may be large: removing it means that tools which
    are just looking for `future-compile` information do not need to
    parse and throw away these fields
  - it does not match the semantics in batch scanning: what is really
    wanted here is a top-level `inputs`, `outputs`, and `depends` set of
    keys because the batch scanning step itself has just one set of
    this information.

Since compilers, build tools, etc. already have mechanisms for
communicating this information around, reusing those rather than
injecting them into the format is likely a better solution.

# Moving `future-compile` keys up one level

Now that the other keys here are gone with the prior point
(`future-link` was dropped in r1 due to its dubious usefulness[1]),
`future-compile`'s keys `outputs`, `provides`, and `requires` keys can
be moved up one level.

# Clarification of header unit representations

C++ has a difference between header units and module units. However,
this is a C++-ism and the format would be useful to use in other
languages as well (namely Fortran) where such a dichotomy does not
exist. As such, formalizing the use of `<>` and `""` wrapping in the
`logical-name` key should be noted for use for C++. Due to the multiple
ways of spelling various includes (e.g., `"boost/version.hpp"`,
`<boost/version.hpp>` or even `<Boost/Version.hpp>` on case-insensitive
filesystems), the `source-path` should be used for linking such uses
together instead.

To do this, the `logical-name` should be the in-source name (for use in
module mapper or other such mechanisms for finding the BMI for a given
module by its name), `source-path` must be provided for header units.
I don't think specifying `<>` and `""` in the format itself is the
greatest, so an additional bool key named `unique-on-source-path` (open
to bikeshedding) would indicate that the `source-path` should be used
for linking between `provide` and `requires` lookups.

Thoughts?

I'm not too keen on the use of `<>` and `""` in the format itself either. It would be fine if we kept "boost/version.hpp" as not having to escape quotes. I'd be ok with the use of some optional boolean key to indicate that it was written as `<boost/version.hpp>`, but we shouldn't have to worry about properly escaping or roundtripping includes between JSON and... literally anything else.

--Ben

[1] The only usecase that we could come up with was MSVC's
`#pragma(comment)` for "autolinking".
_______________________________________________
SG15 mailing list
SG15_at_[hidden]<mailto:SG15%40lists.isocpp.org>
https://lists.isocpp.org/mailman/listinfo.cgi/sg15<https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Flists.isocpp.org%2Fmailman%2Flistinfo.cgi%2Fsg15&data=04%7C01%7Cgdr%40microsoft.com%7Ca40a6e8850e64e4049a908d9160b0457%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637565058841120184%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&sdata=sJEIJuW5bCiDs1uJzOmdmNo7wwTNZ8ct8%2BiEW7k7uic%3D&reserved=0>