This is an archive of the discontinued LLVM Phabricator instance.

[docs][llvm-size] Write llvm-size documentation
ClosedPublic

Authored by jhenderson on Sep 13 2019, 7:56 AM.

Diff Detail

Event Timeline

jhenderson created this revision.Sep 13 2019, 7:56 AM
Herald added a project: Restricted Project. · View Herald TranscriptSep 13 2019, 7:56 AM

LGTM, that's super nice!

This revision is now accepted and ready to land.Sep 13 2019, 1:03 PM
MaskRay added inline comments.Sep 13 2019, 8:11 PM
llvm/docs/CommandGuide/llvm-size.rst
13–14

for object files

Is there a concise term that refers to object files/executables/shared objects/archives collectively? I don't have particular suggestion here.

As a reference, FreeBSD size says:

The size utility lists the sizes of ELF sections, and optionally the total size, for each input file specified on the command line. The size utility can operate on ELF objects, on ar(1) archives containing ELF ob- jects, and on core dumps. If no file name is specified on the command-line, a.out is assumed.

We support Mach-O and PE/COFF so "ELF objects" is not accurate...

162

the total size

The Berkeley format prints more than 1 field, so GNU size refers to them as "totals".

GNU size:

Show totals of all objects listed

FreeBSD size:

Shows cumulative totals of section sizes from all objects.

177

Or simply Display the version of this program. as used by other utilities.

jhenderson marked 2 inline comments as done.Sep 16 2019, 3:41 AM
jhenderson added inline comments.
llvm/docs/CommandGuide/llvm-size.rst
13–14

TL;DR - Either we use "binary" (or possibly "archives and binaries"), or we go with the not-always-correct-but-commonly-used term "object file". Let me know if you have a specific preference.


So technically, "object files" for ELF refers to all ELF types, not just ET_REL objects. For example, the ELF gABI says:

e_type
This member identifies the object file type.

The FreeBSD spec seems to describe the same principle (note that it doesn't highlight executables separately from relocatable objects). On the other hand, wider usage seems to be "object file" = "relocatable object". Similarly, the terminology used in the PE/COFF file format calls executables "executables" and not objects (which is used for reloctable objects specifically). Mach-O uses the term binary. LLVM code seems to be inconsistent (e.g. the ObjectFile class can represent executables or reloctable objects of all supported formats).

We use the term "object files" to refer to any input (except archives) in llvm-symbolizer.rst, and llvm-readobj.rst. In llvm-nm.rst, we use "LLVM bitcode files, object files, and archives". llvm-objcopy uses "objects", so we should use the same terminology throughout the docs for these files. I'm happy to add a specific mention of archives though. I don't have a good way of grouping archives with object files into a single concise term, unless we go with the very imprecise term "binary".

177

I discussed this internally with a colleague and was planning on putting up a patch to change the docs for the other tools to match this version. The reasoning is that everywhere else, we refer to the program by its name e.g. "llvm-size exits with" or "llvm-size reads a file.." rather than "This program exits" etc. Additionally, as this doc isn't part of the executable, referring to the tool as "this program" isn't technically correct.

jhenderson marked 2 inline comments as done.

Address some review comments. Specifically, reworded the --totals description, added a note about archive inputs, and replaced "object files" with "binaries" etc, to be more correct.

Fix formatting of code blocks, so that the text following them are not considered part of the block.

MaskRay accepted this revision.Sep 16 2019, 5:13 AM
This revision was automatically updated to reflect the committed changes.