I would like to extend the

pex_binary

target docstring to comment on packaging multiplatform PEX files. https://github.com/pantsbuild/pants/blob/f9b5815352cb571e98f3214a23b83c86f96ee2a7/src/python/pants/backend/python/target_types.py#L242 So the idea is that it is possible to create multi-platform PEX files so that the very same

.pex

file can be distributed and run both on Linux and MacOS device. This is achieved by adding multiple platform tags for the

pex_binary

target declaration. This will make sure that the

.pex

file contains wheels for both platforms (e.g., if

numpy

is a requirement, then there will be one

.whl

file for

numpy

compiled for MacOS and one

.whl

file for

numpy

compiled for Linux). If there are many requirements with compiled non-Python code, a multi-platform PEX file can be significantly larger than a platform-specific one. It wasn’t clear to me that multiple wheel files will be included (one for each target platform) which became obvious once I have unzipped the

.pex

file and inspected the

.deps

directory. Do you think that it’s worth adding this to the docstring? Do you like this wording or it could be expressed in a better way?

--- a/src/python/pants/backend/python/target_types.py
+++ b/src/python/pants/backend/python/target_types.py
@@ -241,7 +241,9 @@ class PexPlatformsField(StringSequenceField):
     help = (
         "The platforms the built PEX should be compatible with.\n\nThis defaults to the current "
         "platform, but can be overridden to different platforms. You can give a list of multiple "
-        "platforms to create a multiplatform PEX.\n\nTo use wheels for specific "
+        "platforms to create a multiplatform PEX. A multiplatform PEX file will contain platform "
+        "specific wheels for each 3rd party requirement that has some non-Python "
+        "code that requires compilation. \n\nTo use wheels for specific "
         "interpreter/platform tags, you can append them to the platform with hyphens like: "
         'PLATFORM-IMPL-PYVER-ABI (e.g. "linux_x86_64-cp-27-cp27mu", '
         '"macosx_10.12_x86_64-cp-36-cp36m"):\n\n  - PLATFORM: the host platform, e.g. '

If you found the docstring lacking then that is good evidence that it should be fixed! Feel free to send a PR with this new phrasing.

okay, thank you @happy-kitchen-89482, I’ll submit a PR, then someone from the main team could review the wording, if necessary

Thanks!