[Distutils] command line versus python API for build system abstraction (was Re: build system abstraction PEP)

[Nathaniel Smith]

On Mon, Nov 9, 2015 at 6:11 PM, Robert Collins
<robertc at robertcollins.net> wrote:
> On 10 November 2015 at 15:03, Nathaniel Smith <njs at pobox.com> wrote:
>> On Sun, Nov 8, 2015 at 5:28 PM, Robert Collins
>> <robertc at robertcollins.net> wrote:
>>> +The use of a command line API rather than a Python API is a little
>>> +contentious. Fundamentally anything can be made to work, and Robert wants to
>>> +pick something thats sufficiently lowest common denominator that
>>> +implementation is straight forward on all sides. Picking a CLI for that makes
>>> +sense because all build systems will need a CLI for end users to use anyway.
>>
>> I agree that this is not terribly important, and anything can be made
>> to work. Having pondered it all for a few more weeks though I think
>> that the "entrypoints-style" interface actually is unambiguously
>> better, so let me see about making that case.
>>
>> What's at stake?
>> ----------------------
>>
>> Option 1, as in Robert's PEP:
>>
>> The build configuration file contains a string like "flit
>> --dump-build-description" (or whatever), which names a command to run,
>> and then a protocol for running this command to get information on the
>> actual build system interface. Build operations are performed by
>> executing these commands as subprocesses.
>>
>> Option 2, my preference:
>>
>> The build configuration file contains a string like
>> "flit:build_system_api" (or whatever) which names a Python object
>> accessed like
>>
>>   import flit
>>   flit.build_system_api
>>
>> (This is the same syntax used for naming entry points.) Which would
>> then have attributes and methods describing the actual build system
>> interface. Build operations are performed by calling these methods.
>
> Option 3 expressed by Donald on IRC

Where is this IRC channel, btw? :-)

> (and implied by his 'smaller step'
> email - hard code the CLI).
>
> A compromise position from 'setup.py <what we do there' is to encode
> the 'setup.py' step in pypa.json, but define the rest as a fixed
> contract, e.g. with subcommands like wheel, metadata etc. This drops
> the self describing tool blob and the caching machinery.

So this would give up on having schema versioning for the API, I guess?

> I plan on using that approach in my next draft.
>
> Your point about bugs etc is interesting, but the use of stdin etc in
> a dedicated Python API also needs to be specified.

Yes, but this specification is trivial:

"Stdin is unspecified, and stdout/stderr can be used for printing
status messages, errors, etc. just like you're used to from every
other build system in the world."

Similarly, we still have to specify how what the different operations
are, what arguments they take, how they signal errors, etc. The point
though is this specification will be shorter and simpler if we're
specifying Python APIs than if we're specifying IPC APIs, because with
a Python API we get to assume the existence of things like data
structures and kwargs and exceptions and return values instead of
having to build them from scratch.

-n

-- 
Nathaniel J. Smith -- http://vorpus.org