Add build-system in pyproject.toml docs

[pawamoy]

• I have searched the issues of this repo and believe that this is not a duplicate.

Issue

I just started using poetry. I set it up for an existing project. So I did not run poetry new, nor poetry init, because I already had a pyproject.toml and wasn't sure if it was going to be overwritten (and also because I did not want to use the interactive setup).

So I wrote my pyproject.toml by hand, by copying the example given in the README.

But I couldn't find anywhere in the docs or the README what the build-system should look like!

I finally found it in another issue: #321.

[build-system]
requires = ["poetry>=0.12"]
build-backend = "poetry.masonry.api"

It's not like an option or else, it's actually mandatory 🙂, so this should be added in the docs, and in the README.

[jacebrowning]

Maybe $ poetry check should warn about this? Or even update the pyproject.toml automatically?

[cjw296]

I think poetry should also add this to pyproject.toml files that it generates, otherwise isn't it failing to implemented PEP-518 properly?
(so I don't think this is just a documentation thing, and I'm afraid I think it's technically a bug not an enhancement...)

[sdispater]

This has been available for quite some time now: https://poetry.eustace.io/docs/pyproject/#poetry-and-pep-517

The init command also adds it automatically.

[hyliu1989]

When I look for the documentation of the tag [build-system], I did not find anything but just found this thread and a reference to how this tag will be added automatically to the toml file when running poetry init.

The above gives me a sense of "This [build-system] thing is just a boilerplate and its content is not that important". However that is not the case in this thread. The tag [build-system] is actually used to solve a problem, where I encountered another problem to it as well.

I know that there is already a documentation explaining what each section in the toml file is aiming for but I did not find one for [build-system]. Can you please reopen this request and add the documentation of [build-system]?

[sinoroc]

@hyliu1989

It's here: https://python-poetry.org/docs/pyproject/#poetry-and-pep-517

In case, you feel like it is not the right location, where would you rather have this section of documentation?

[hyliu1989]

It is not user friendly as a user has to read through the entire PEP 517 just to know how to add that dependency. A summary of PEP 517 for most used cases will be appreciated. Those cases include building extensions, building extensions which require some build time packages to be installed first, etc. In my case, numpy and cython has to be installed in order to compile the c codes properly.

As far as I understand correctly, the immediate documentation in the link above focuses on replacing poetry with poetry.core. This clouds the user from knowing that it also includes how to work with non-Python extensions.

Another related topic is the build tool mentioned in #11. It will be great to see how it is going to be implemented, though I have some concern that implementing that may ended up having the same problem setup.py is facing.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.