Description of datas and binaries needs to be clarified

[htgoebel]

From the mailinglist:

It turns out that I was using binaries to include binary programs that I call using subprocess.call() rather than datas. I did this because the "Using Spec Files" section of the docs says, "datas: non-binary files included in the app."

So we need to clarify in the manual what are binaries and what is data.

[thekswenson]

The current version of the documentation is:
"""
binaries: non-python modules needed by the scripts, including names given by the --add-binary option;
datas: non-binary files included in the app, including names given by the --add-data option.
"""

I was thinking of modifying the datas line to be:
"datas: files used by the app but not included with binaries, including names given by the --add-data option."

It's hard to do better since I'm not sure what binaries is exactly.

[tallforasmurf]

The difference was not clear to me when I wrote the current doc, either! Somebody needs to dive into the code and find out what the real, functional difference is between the two categories. Presumably "binary" files are handled differently than "data" files? Stored elsewhere? Unpacked differently?

[thekswenson]

I know that I've used the "datas" list to include binary files compiled with Cython, and for binaries called using subprocess.call(). Is binaries even necessary?

[springermac]

binaries are analyzed for binary dependencies, i.e., dlls, so, etc., before being bundled. datas are only bundled.

[thekswenson]

Would this be a better entry?

"""
binaries: binary dependencies (e.g. dll, so, etc.) to be analyzed, including names given by the --add-binary option;
datas: non-binary files included in the app, including names given by the --add-data option.
"""

[springermac]

I would replace non-binary with static since in especially one file mode any modifications to included files will not persist.

[htgoebel]

First of all, I would switch the order, so datas is the more standard type. Something like this:

• datas: static files to be included with the app, including names given by the --add-data option
• binaries: binary dependencies (e.g. dll, so, etc.) including names given by the --add-binary option. Files listed here will be analyzed to find recursive dependencies, stripped (in case strip==True) and cached.

We should also update the usage (in building/makespec.py::__add_options()) accordingly.