llvm/docs/CommandGuide/llvm-ifs.md - llvm-project.git - Git at Google

 # llvm-ifs - shared object stubbing tool

 ```{program} llvm-ifs
 ```

 ## SYNOPSIS

 {program}`llvm-ifs` \[*options*\] *inputs*

 ## DESCRIPTION

 {program}`llvm-ifs` is a tool that jointly produces human-readable text-based
 stubs (.ifs files) for shared objects and linkable shared object stubs
 (.so files) from either ELF shared objects or text-based stubs. The text-based
 stubs is useful for monitoring ABI changes of the shared object. The linkable
 shared object stubs can be used to avoid unnecessary relinks when the ABI of
 shared libraries does not change.

 ## IFS FORMATS

 Here is an example of the text representation (IFS) of a shared object produced
 by the {program}`llvm-ifs`:

 ```
 --- !ifs-v1
 IFSVersion: 3.0
 SoName: libtest.so /* Optional */
 Target: x86_64-unknown-linux-gnu   /* Optional, format 1, same format as llvm target triple */
 Target: { Arch: x86_64, Endianness: little, Bitwidth: 64 } /* Optional, format 2 */
 NeededLibs:
   - libc.so.6
 Symbols:
   - { Name: sym0, Type: Notype }
   - { Name: sym1, Type: Object, Size: 0 }
   - { Name: sym2, Type: Func, Weak: false }
   - { Name: sym3, Type: TLS }
   - { Name: sym4, Type: Unknown, Warning: foo }
 ...
 ```

 - `IFSVersion`: Version of the IFS file for reader compatibility.

 - `SoName` (optional): Name of the shared object file that is being stubbed.

 - `Target` (optional): The architecture, endianness and bitwise information of
   this shared object. It can be either in explicit format or in implicit LLVM
   triple format. It can be optional and can be overridden from command line
   options.

 - `NeededLibs`: The list of the external shared objects that this library depends on.

 - `Symbols`: A collection of all data needed to link objects for each symbol, sorted by name in ascending order.

   - `Name`: Symbol name.
   - `Type`: Whether the symbol is an object, function, no-type, thread local storage, or unknown. Symbol types not explicitly supported are mapped as unknown to improve signal-to-noise ratio.
   - `Size`: The size of the symbol in question, doesn't apply to functions, and is optional for NoType symbols.
   - `Undefined`: Whether or not the symbol is defined in this shared object file.
   - `Weak`: Whether or not the symbol should be treated as weak.
   - `Warning` (optional): Warning text to output when this symbol is linked against.

 This YAML based text format contains everything that is needed to generate a
 linkable ELF shared object as well as an Apple TAPI format file. The ordering
 of symbols is sorted, so these files can be easily compared using diff tools.
 If the content of the file changes, it indicates a potentially ABI breaking
 change.

 ## ELF STUB FORMAT

 A minimum ELF file that can be used by linker should have following sections properly populated:

 - ELF header.

 - Section headers.

 - Dynamic symbol table (`.dynsym` section).

 - Dynamic string table (`.dynstr` section).

 - Dynamic table (`.dynamic` section).

   - `DT_SYMTAB` entry.
   - `DT_STRTAB` entry.
   - `DT_STRSZ` entry.
   - `DT_NEEDED` entries. (optional)
   - `DT_SONAME` entry. (optional)

 - Section header string table (`.shstrtab` section)

 This ELF file may have compatibility issues with ELF analysis tools that rely on the program headers.
 Linkers like LLD work fine with such a minimum ELF file without errors.

 ## OPTIONS

 :::{option} --input-format=[IFS|ELF|OtherObjectFileFormats]
 Specify input file format. Currently, only text IFS files and ELF shared
 object files are supported. This flag is optional as the input format can be
 inferred.
 :::

 :::{option} --output-elf=<output-filename>
 Specify the output file for ELF shared object stub.
 :::

 :::{option} --output-ifs=<output-filename>
 Specify the output file for text IFS.
 :::

 :::{option} --output-tbd=<output-filename>
 Specify the output file for Apple TAPI tbd.
 :::

 :::{option} --arch=[x86_64|AArch64|...]
 This flag is optional and it should only be used when reading an IFS file
 which does not define the `Arch` (architecture). This flag defines the
 architecture of the output file, and can be any string supported by ELF
 'e_machine' field. If the value is conflicting with the IFS file, an error
 will be reported and the program will stop.
 :::

 :::{option} --endianness=[little|big]
 This flag is optional and it should only be used when reading an IFS file
 which does not define the `Endianness`. This flag defines the endianness of
 the output file. If the value is conflicting with the IFS file, an error
 will be reported and the program will stop.
 :::

 :::{option} --bitwidth=[32|64]
 This flag is optional and it should only be used when reading an IFS file
 which does not define the `BitWidth`. This flag defines the bit width of the
 output file. If the value is conflicting with the input IFS file, an error
 will be reported and the program will stop.
 :::

 :::{option} --target=<target triple>
 This flag is optional and should only be used when reading an IFS file
 which does not define any target information. This flag defines architecture,
 endianness and bit width of the output file using llvm target triple.
 This flag cannot be used simultaneously with other target related flags.
 :::

 :::{option} --hint-ifs-target=<target triple>
 This flag is optional and should only be used when reading an ELF shared
 object and generating an IFS file. by default, llvm-ifs will use '`Arch`,
 `Endianness` and `BitWidth`' fields to reflect the target information from the
 input object file. Using this flag will tell llvm-ifs the expected target
 triple in the output IFS file. If the value matches the target information
 from the object file, this value will be used in the 'Target:' filed in the
 generated IFS. If it conflicts with the input object file, an error will be
 reported and the program will stop.
 :::

 :::{option} --hint-ifs-target
 This flag is optional and should only be used when outputting an IFS file.
 This flag strips the `Arch` field from the IFS file so it can be overridden
 later.
 :::

 :::{option} --strip-ifs-endianness
 This flag is optional and should only be used when outputting an IFS file.
 This flag strips the `Endianness` field from the IFS file so it can be
 overridden later.
 :::

 :::{option} --strip-ifs-bitwidth
 This flag is optional and should only be used when outputting an IFS file.
 This flag strips the `BitWidth` field from the IFS file so it can be overridden
 later.
 :::

 :::{option} --strip-ifs-target
 This flag is optional and should only be used when outputting an IFS file.
 This flag strips the `Target` field from the IFS file so it can be overridden
 later.
 :::

 :::{option} --write-if-changed
 When this flag is set, llvm-ifs will only write the output file if it does not
 already exist or the content will be different from the existing file.
 :::

 :::{option} --strip-size
 When this flag is set, llvm-ifs will remove the size field from the output ifs
 file. This is useful for shared objects that only intend to be linked against
 position independent code which doesn't need copy relocations, or where the size
 of an object is not a useful part of the abi to track.
 :::

 ## EXIT STATUS

 If {program}`llvm-ifs` succeeds, it will exit with 0. Otherwise, if an
 error occurs, it will exit with a non-zero value.
	# llvm-ifs - shared object stubbing tool

	```{program} llvm-ifs
	```

	## SYNOPSIS

	{program}`llvm-ifs` \[options\] inputs

	## DESCRIPTION

	{program}`llvm-ifs` is a tool that jointly produces human-readable text-based
	stubs (.ifs files) for shared objects and linkable shared object stubs
	(.so files) from either ELF shared objects or text-based stubs. The text-based
	stubs is useful for monitoring ABI changes of the shared object. The linkable
	shared object stubs can be used to avoid unnecessary relinks when the ABI of
	shared libraries does not change.

	## IFS FORMATS

	Here is an example of the text representation (IFS) of a shared object produced
	by the {program}`llvm-ifs`:

	```
	--- !ifs-v1
	IFSVersion: 3.0
	SoName: libtest.so /* Optional */
	Target: x86_64-unknown-linux-gnu /* Optional, format 1, same format as llvm target triple */
	Target: { Arch: x86_64, Endianness: little, Bitwidth: 64 } /* Optional, format 2 */
	NeededLibs:
	- libc.so.6
	Symbols:
	- { Name: sym0, Type: Notype }
	- { Name: sym1, Type: Object, Size: 0 }
	- { Name: sym2, Type: Func, Weak: false }
	- { Name: sym3, Type: TLS }
	- { Name: sym4, Type: Unknown, Warning: foo }
	...
	```

	- `IFSVersion`: Version of the IFS file for reader compatibility.

	- `SoName` (optional): Name of the shared object file that is being stubbed.

	- `Target` (optional): The architecture, endianness and bitwise information of
	this shared object. It can be either in explicit format or in implicit LLVM
	triple format. It can be optional and can be overridden from command line
	options.

	- `NeededLibs`: The list of the external shared objects that this library depends on.

	- `Symbols`: A collection of all data needed to link objects for each symbol, sorted by name in ascending order.

	- `Name`: Symbol name.
	- `Type`: Whether the symbol is an object, function, no-type, thread local storage, or unknown. Symbol types not explicitly supported are mapped as unknown to improve signal-to-noise ratio.
	- `Size`: The size of the symbol in question, doesn't apply to functions, and is optional for NoType symbols.
	- `Undefined`: Whether or not the symbol is defined in this shared object file.
	- `Weak`: Whether or not the symbol should be treated as weak.
	- `Warning` (optional): Warning text to output when this symbol is linked against.

	This YAML based text format contains everything that is needed to generate a
	linkable ELF shared object as well as an Apple TAPI format file. The ordering
	of symbols is sorted, so these files can be easily compared using diff tools.
	If the content of the file changes, it indicates a potentially ABI breaking
	change.

	## ELF STUB FORMAT

	A minimum ELF file that can be used by linker should have following sections properly populated:

	- ELF header.

	- Section headers.

	- Dynamic symbol table (`.dynsym` section).

	- Dynamic string table (`.dynstr` section).

	- Dynamic table (`.dynamic` section).

	- `DT_SYMTAB` entry.
	- `DT_STRTAB` entry.
	- `DT_STRSZ` entry.
	- `DT_NEEDED` entries. (optional)
	- `DT_SONAME` entry. (optional)

	- Section header string table (`.shstrtab` section)

	This ELF file may have compatibility issues with ELF analysis tools that rely on the program headers.
	Linkers like LLD work fine with such a minimum ELF file without errors.

	## OPTIONS

	:::{option} --input-format=[IFS\|ELF\|OtherObjectFileFormats]
	Specify input file format. Currently, only text IFS files and ELF shared
	object files are supported. This flag is optional as the input format can be
	inferred.
	:::

	:::{option} --output-elf=<output-filename>
	Specify the output file for ELF shared object stub.
	:::

	:::{option} --output-ifs=<output-filename>
	Specify the output file for text IFS.
	:::

	:::{option} --output-tbd=<output-filename>
	Specify the output file for Apple TAPI tbd.
	:::

	:::{option} --arch=[x86_64\|AArch64\|...]
	This flag is optional and it should only be used when reading an IFS file
	which does not define the `Arch` (architecture). This flag defines the
	architecture of the output file, and can be any string supported by ELF
	'e_machine' field. If the value is conflicting with the IFS file, an error
	will be reported and the program will stop.
	:::

	:::{option} --endianness=[little\|big]
	This flag is optional and it should only be used when reading an IFS file
	which does not define the `Endianness`. This flag defines the endianness of
	the output file. If the value is conflicting with the IFS file, an error
	will be reported and the program will stop.
	:::

	:::{option} --bitwidth=[32\|64]
	This flag is optional and it should only be used when reading an IFS file
	which does not define the `BitWidth`. This flag defines the bit width of the
	output file. If the value is conflicting with the input IFS file, an error
	will be reported and the program will stop.
	:::

	:::{option} --target=<target triple>
	This flag is optional and should only be used when reading an IFS file
	which does not define any target information. This flag defines architecture,
	endianness and bit width of the output file using llvm target triple.
	This flag cannot be used simultaneously with other target related flags.
	:::

	:::{option} --hint-ifs-target=<target triple>
	This flag is optional and should only be used when reading an ELF shared
	object and generating an IFS file. by default, llvm-ifs will use '`Arch`,
	`Endianness` and `BitWidth`' fields to reflect the target information from the
	input object file. Using this flag will tell llvm-ifs the expected target
	triple in the output IFS file. If the value matches the target information
	from the object file, this value will be used in the 'Target:' filed in the
	generated IFS. If it conflicts with the input object file, an error will be
	reported and the program will stop.
	:::

	:::{option} --hint-ifs-target
	This flag is optional and should only be used when outputting an IFS file.
	This flag strips the `Arch` field from the IFS file so it can be overridden
	later.
	:::

	:::{option} --strip-ifs-endianness
	This flag is optional and should only be used when outputting an IFS file.
	This flag strips the `Endianness` field from the IFS file so it can be
	overridden later.
	:::

	:::{option} --strip-ifs-bitwidth
	This flag is optional and should only be used when outputting an IFS file.
	This flag strips the `BitWidth` field from the IFS file so it can be overridden
	later.
	:::

	:::{option} --strip-ifs-target
	This flag is optional and should only be used when outputting an IFS file.
	This flag strips the `Target` field from the IFS file so it can be overridden
	later.
	:::

	:::{option} --write-if-changed
	When this flag is set, llvm-ifs will only write the output file if it does not
	already exist or the content will be different from the existing file.
	:::

	:::{option} --strip-size
	When this flag is set, llvm-ifs will remove the size field from the output ifs
	file. This is useful for shared objects that only intend to be linked against
	position independent code which doesn't need copy relocations, or where the size
	of an object is not a useful part of the abi to track.
	:::

	## EXIT STATUS

	If {program}`llvm-ifs` succeeds, it will exit with 0. Otherwise, if an
	error occurs, it will exit with a non-zero value.