Skip to content

Commit add2723

Browse files
andrurogerzandrurogerz
authored
docs: add some build, usage documentation
Provide some documentation for building and using `idt`. Provide some documentation on how to define the ABI annotation macros to allow others to quickly start annotating their ABI surface and use the tool to analyze their library interfaces.
1 parent b14bf55 commit add2723

File tree

4 files changed

+206
-1
lines changed

4 files changed

+206
-1
lines changed

‎Docs/Building.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Building IDS
2+
3+
IDS can be built either as an LLVM external project or as a stand-alone project.
4+
5+
## LLVM External Project
6+
7+
IDS can be built as a sub-project of LLVM by setting `LLVM_EXTERNAL_PROJECTS`.
8+
This greatly improves the editing and debugging experience in Visual Studio when
9+
navigating to Clang code from the IDS code. Please see [Getting Started with the
10+
LLVM
11+
Project](https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm)
12+
for more info on building LLVM and Clang.
13+
14+
The CMake variables `LLVM_EXTERNAL_PROJECTS` and `LLVM_EXTERNAL_IDS_SOURCE_DIR`
15+
variables must be set for IDS to build as part of the LLVM build.
16+
17+
Testing IDS also requires `LIT_EXECUTABLE` and `FILECHECK_EXECUTABLE` to specify
18+
the locations of `lit.py` and `FileCheck`, which are located in the LLVM source
19+
and LLVM build output directory.
20+
21+
```bash
22+
cmake -G Ninja \
23+
-B /home/user/src/llvm-project/build \
24+
-S /home/user/src/llvm-project/llvm \
25+
-DCMAKE_BUILD_TYPE=Release \
26+
-DLLVM_ENABLE_PROJECTS="llvm;clang" \
27+
-DLLVM_EXTERNAL_PROJECTS="IDS" \
28+
-DLLVM_EXTERNAL_IDS_SOURCE_DIR="/home/user/src/ids" \
29+
-DLIT_EXECUTABLE=/home/user/src/llvm-project/llvm/utils/lit/lit.py \
30+
-DFILECHECK_EXECUTABLE=/home/user/src/llvm-project/build/bin/FileCheck
31+
32+
cmake --build /home/user/src/llvm-project/build --target idt
33+
cmake --build /home/user/src/llvm-project/build --target check-ids
34+
```
35+
36+
## Stand-Alone Build
37+
38+
To build IDS as a stand-alone project, `LLVM_DIR` and `Clang_DIR` variables must
39+
be provided to specify the locations of local LLVM and Clang libraries. These
40+
can refer to locally built LLVM and Clang libraries, or to pre-built LLVM
41+
package that includes the Clang development libraries.
42+
43+
Testing IDS also requires `LIT_EXECUTABLE` and `FILECHECK_EXECUTABLE` to specify
44+
the locations of `lit.py` and `FileCheck` , which are not typically included in
45+
a pre-built LLVM package.
46+
47+
```bash
48+
cmake -G Ninja \
49+
-B /home/user/src/ids/build \
50+
-S home/user/src/ids \
51+
-DCMAKE_BUILD_TYPE=Release \
52+
-DLIT_EXECUTABLE=/home/user/src/llvm-project/llvm/utils/lit/lit.py \
53+
-DFILECHECK_EXECUTABLE=/home/user/src/llvm-project/build/bin/FileCheck \
54+
-DLLVM_DIR=/home/user/src/llvm-project/build/lib/cmake/llvm \
55+
-DClang_DIR=/home/user/src/llvm-project/build/lib/cmake/clang
56+
57+
cmake --build S:\ids\build --target idt
58+
cmake --build S:\ids\build --target check-ids
59+
```

‎Docs/ExportMacroDefinitions.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Export Macro Definitions
2+
3+
A common approach for annotating project’s public interface is by defining a
4+
set of preprocessor macros that are used instead of adding annotations directly
5+
to the source. This approach allows supporting visibility annotations
6+
(`[[gnu::visibility]]`, `__visibility__`) when building for Linux and MacOS and
7+
DLL import/export annotations (`__declspec(dllimport)`,
8+
`__declspec(dllexport)`) when building for Windows.
9+
10+
For example, the `Project_ABI` macro defined below can be added to symbols in a
11+
project’s header files files that should be externally visible.
12+
13+
```cpp
14+
#if defined(PROJECT_STATIC)
15+
/* We are building Project as a static library (no exports) */
16+
# define Project_ABI
17+
#else
18+
/* We are building Project as a shared library */
19+
# if defined(_WIN32)
20+
# if defined(Project_EXPORTS)
21+
/* We are building this library */
22+
# define Project_ABI __declspec(dllexport)
23+
# else
24+
/* We are using this library */
25+
# define Project_ABI __declspec(dllimport)
26+
# endif
27+
# else
28+
# define Project_ABI __visibility__((__visibility__("default")))
29+
# endif
30+
#endif
31+
```
32+
33+
A Windows project using these macros must be built with `Project_EXPORTS`
34+
defined so that public symbols are annotated for export with
35+
`__declspec(dllexport)`. When building clients of the project, however,
36+
`Project_EXPORTS` must not be defined so the same set of public symbols will be
37+
properly annotated for import with `__declspec(dllimport)`.
38+
39+
An ELF shared library or Mach-O dylib project will have all symbols publicly
40+
visible by default so annotations are not strictly required. However, when a
41+
project is built with default hidden symbol visibility using
42+
`-fvisibility-default=hidden`, individual symbols must be explicitly exported
43+
using a visibility annotations.
44+
45+
## CMake Support
46+
When building with CMake, the `generate_export_header()` function can be used
47+
to auto-generate a header with appropriate export macro definitions. See [CMake
48+
documentation](https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html)
49+
for details.

‎Docs/Running.md

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Running IDS
2+
3+
There are a number of command-line arguments to IDS that dictate its behavior.
4+
5+
```bash
6+
USAGE: idt [options] <source0> [... <sourceN>]
7+
8+
OPTIONS:
9+
10+
Generic Options:
11+
12+
--help - Display available options (--help-hidden for more)
13+
--help-list - Display list of available options (--help-list-hidden for more)
14+
--version - Display the version of this program
15+
16+
interface definition scanner options:
17+
18+
--apply-fixits - Apply suggested changes to decorate interfaces
19+
--export-macro=<define> - The macro to decorate interfaces with
20+
--extra-arg=<string> - Additional argument to append to the compiler command line
21+
--extra-arg-before=<string> - Additional argument to prepend to the compiler command line
22+
--ignore=<function-name[,function-name...]> - Ignore one or more functions
23+
--include-header=<header> - Header required for export macro
24+
--inplace - Apply suggested changes in-place
25+
-p <string> - Build path
26+
```
27+
28+
At a minimum, the `--export-macro` argument must be provided to specify the
29+
macro used to annotate public symbols. See [Export Macro
30+
Definitions](Docs/ExportMacroDefinitions.md) for details. Additionally, at
31+
least one source file must be specified as a positional argument.
32+
33+
While it is possible to specify a number of source files, IDS generally works
34+
better when invoked to process one file at a time.
35+
36+
## Windows Example
37+
38+
```powershell
39+
S:\Source\ids\build\bin\idt.exe `
40+
-p S:\Source\MyProject\build `
41+
--apply-fixits `
42+
--inplace `
43+
--export-macro=PUBLIC_ABI `
44+
--include-header="include/MyAnnotations.h" `
45+
--extra-arg="-DPUBLIC_ABI=__declspec(dllexport)" `
46+
--extra-arg="-Wno-macro-redefined" `
47+
--extra-arg="-fno-delayed-template-parsing" `
48+
S:\Source\MyProject\include\ProjectHeader1.h `
49+
S:\Source\MyProject\include\ProjectHeader2.h
50+
```
51+
52+
## Linux Example
53+
54+
```bash
55+
/home/user/src/ids/out/bin/idt \
56+
-p /home/user/src/MyProject/build \
57+
--apply-fixits \
58+
--inplace \
59+
--export-macro=PUBLIC_ABI \
60+
--include-header="include/MyAnnotations.h" \
61+
--extra-arg='-DLLVM_ABI=[[gnu::visibility("default")]]' \
62+
--extra-arg="-Wno-macro-redefined" \
63+
S:\Source\MyProject\include\ProjectHeader1.h \
64+
S:\Source\MyProject\include\ProjectHeader2.h
65+
```
66+
67+
The arguments in the above examples have the following effects:
68+
- `-p` refers to the build directory for the project containing a
69+
`compile_commands.json` file used by IDS to configure build options
70+
- `--apply-fixits` and `--inplace` instruct IDS to modify the source file in
71+
place
72+
- `--export-macro` indicates that the `PUBLIC_ABI` macro will be used to
73+
annotate public symbols
74+
- `--include-header` specifies a local header file that will be added as a
75+
`#include` in the processed source files if needed. This would typically
76+
refer to the header file containing the export macro definition.
77+
- The first two `--extra-arg` arguments ensure that `PUBLIC_ABI` is always
78+
defined (differently for Windows and Linux), and suppress the warning emitted
79+
if it already is. These arguments ensure the `PUBLIC_ABI` annotation is not
80+
mistakenly added to a symbol that already has it.
81+
- The third `--extra-arg` argument is Windows-specific and ensures that
82+
templates are always expanded while parsing. It is ensures overloaded private
83+
methods get properly exported when referenced only from inline templates.
84+
- The trailing positional arguments are the names of source files for IDS to
85+
scan.
86+

‎README.md

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,13 @@
11
# Interface Definition Scanner (IDS)
2-
Interface Analysis Utility
2+
3+
IDS is tool for automatically identifying and annotating the public interface of
4+
a C++ project. It is built on Clang’s
5+
[LibTooling](https://clang.llvm.org/docs/LibTooling.html) framework. It is
6+
primarily designed for adding import/export annotations to a Windows DLL
7+
project, but can also be used to add visibility annotations for ELF shared
8+
library or Mach-O dylib projects.
9+
10+
## Documentation
11+
- [Building IDS](Docs/Building.md)
12+
- [Running IDS](Docs/Running.md)
13+
- [Export Macro Definitions](Docs/ExportMacroDefinitions.md)

0 commit comments

Comments
 (0)