[PATCH] D67555: [docs][llvm-size] Write llvm-size documentation

[James Henderson via Phabricator via llvm-commits]

jhenderson marked 2 inline comments as done.
jhenderson added inline comments.


================
Comment at: llvm/docs/CommandGuide/llvm-size.rst:14
 
 :program:`llvm-size` is a tool that prints size information for object files.
+It is intended to be a drop-in replacement for GNU's :program:`size`.
----------------
MaskRay wrote:
> > 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...
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".


================
Comment at: llvm/docs/CommandGuide/llvm-size.rst:178
+
+ Display the version of the :program:`llvm-size` executable.
+
----------------
MaskRay wrote:
> Or simply `Display the version of this program.` as used by other utilities.
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.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D67555/new/

https://reviews.llvm.org/D67555