Skip to content

Commit 2a82967

Browse files
andrurogerzandrurogerz
committed
[doc] split out documentation from README.md
1 parent 394a509 commit 2a82967

File tree

3 files changed

+149
-145
lines changed

3 files changed

+149
-145
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/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: 4 additions & 145 deletions
Original file line numberDiff line numberDiff line change
@@ -7,148 +7,7 @@ primarily designed for adding import/export annotations to a Windows DLL
77
project, but can also be used to add visibility annotations for ELF shared
88
library or Mach-O dylib projects.
99

10-
## Building IDS
11-
12-
IDS can be built either as an LLVM external project or as a stand-alone project.
13-
14-
### LLVM External Project
15-
16-
IDS can be built as a sub-project of LLVM by setting `LLVM_EXTERNAL_PROJECTS`.
17-
This greatly improves the editing and debugging experience in Visual Studio when
18-
navigating to Clang code from the IDS code. Please see [Getting Started with the
19-
LLVM
20-
Project](https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm)
21-
for more info on building LLVM and Clang.
22-
23-
The CMake variables `LLVM_EXTERNAL_PROJECTS` and `LLVM_EXTERNAL_IDS_SOURCE_DIR`
24-
variables must be set for IDS to build as part of the LLVM build.
25-
26-
Testing IDS also requires `LIT_EXECUTABLE` and `FILECHECK_EXECUTABLE` to specify
27-
the locations of `lit.py` and `FileCheck`, which are located in the LLVM source
28-
and LLVM build output directory.
29-
30-
```bash
31-
cmake -G Ninja \
32-
-B /home/user/src/llvm-project/build \
33-
-S /home/user/src/llvm-project/llvm \
34-
-DCMAKE_BUILD_TYPE=Release \
35-
-DLLVM_ENABLE_PROJECTS="llvm;clang" \
36-
-DLLVM_EXTERNAL_PROJECTS="IDS" \
37-
-DLLVM_EXTERNAL_IDS_SOURCE_DIR="/home/user/src/ids" \
38-
-DLIT_EXECUTABLE=/home/user/src/llvm-project/llvm/utils/lit/lit.py \
39-
-DFILECHECK_EXECUTABLE=/home/user/src/llvm-project/build/bin/FileCheck
40-
41-
cmake --build /home/user/src/llvm-project/build --target idt
42-
cmake --build /home/user/src/llvm-project/build --target check-ids
43-
```
44-
45-
### Stand-Alone Build
46-
47-
To build IDS as a stand-alone project, `LLVM_DIR` and `Clang_DIR` variables must
48-
be provided to specify the locations of local LLVM and Clang libraries. These
49-
can refer to locally built LLVM and Clang libraries, or to pre-built LLVM
50-
package that includes the Clang development libraries.
51-
52-
Testing IDS also requires `LIT_EXECUTABLE` and `FILECHECK_EXECUTABLE` to specify
53-
the locations of `lit.py` and `FileCheck` , which are not typically included in
54-
a pre-built LLVM package.
55-
56-
```bash
57-
cmake -G Ninja \
58-
-B /home/user/src/ids/build \
59-
-S home/user/src/ids \
60-
-DCMAKE_BUILD_TYPE=Release \
61-
-DLIT_EXECUTABLE=/home/user/src/llvm-project/llvm/utils/lit/lit.py \
62-
-DFILECHECK_EXECUTABLE=/home/user/src/llvm-project/build/bin/FileCheck \
63-
-DLLVM_DIR=/home/user/src/llvm-project/build/lib/cmake/llvm \
64-
-DClang_DIR=/home/user/src/llvm-project/build/lib/cmake/clang
65-
66-
cmake --build S:\ids\build --target idt
67-
cmake --build S:\ids\build --target check-ids
68-
```
69-
70-
## Running IDS
71-
72-
There are a number of command-line arguments to IDS that dictate its behavior.
73-
74-
```bash
75-
USAGE: idt [options] <source0> [... <sourceN>]
76-
77-
OPTIONS:
78-
79-
Generic Options:
80-
81-
--help - Display available options (--help-hidden for more)
82-
--help-list - Display list of available options (--help-list-hidden for more)
83-
--version - Display the version of this program
84-
85-
interface definition scanner options:
86-
87-
--apply-fixits - Apply suggested changes to decorate interfaces
88-
--export-macro=<define> - The macro to decorate interfaces with
89-
--extra-arg=<string> - Additional argument to append to the compiler command line
90-
--extra-arg-before=<string> - Additional argument to prepend to the compiler command line
91-
--ignore=<function-name[,function-name...]> - Ignore one or more functions
92-
--include-header=<header> - Header required for export macro
93-
--inplace - Apply suggested changes in-place
94-
-p <string> - Build path
95-
```
96-
97-
At a minimum, the `--export-macro` argument must be provided to specify the
98-
macro used to annotate public symbols. See [Export Macro
99-
Definitions](Docs/ExportMacroDefinitions.md) for details. Additionally, at
100-
least one source file must be specified as a positional argument.
101-
102-
While it is possible to specify a number of source files, IDS generally works
103-
better when invoked to process one file at a time.
104-
105-
### Windows Example
106-
107-
```powershell
108-
S:\Source\ids\build\bin\idt.exe `
109-
-p S:\Source\MyProject\build `
110-
--apply-fixits `
111-
--inplace `
112-
--export-macro=PUBLIC_ABI `
113-
--include-header="include/MyAnnotations.h" `
114-
--extra-arg="-DPUBLIC_ABI=__declspec(dllexport)" `
115-
--extra-arg="-Wno-macro-redefined" `
116-
--extra-arg="-fno-delayed-template-parsing" `
117-
S:\Source\MyProject\include\ProjectHeader1.h `
118-
S:\Source\MyProject\include\ProjectHeader2.h
119-
```
120-
121-
### Linux Example
122-
123-
```bash
124-
/home/user/src/ids/out/bin/idt \
125-
-p /home/user/src/MyProject/build \
126-
--apply-fixits \
127-
--inplace \
128-
--export-macro=PUBLIC_ABI \
129-
--include-header="include/MyAnnotations.h" \
130-
--extra-arg="-DLLVM_ABI=[[gnu::visibility(\"default\")]]" \
131-
--extra-arg="-Wno-macro-redefined" \
132-
S:\Source\MyProject\include\ProjectHeader1.h \
133-
S:\Source\MyProject\include\ProjectHeader2.h
134-
```
135-
136-
The arguments in the above examples have the following effects:
137-
- `-p` refers to the build directory for the project containing a
138-
`compile_commands.json` file used by IDS to configure build options
139-
- `--apply-fixits` and `--inplace` instruct IDS to modify the source file in
140-
place
141-
- `--export-macro` indicates that the `PUBLIC_ABI` macro will be used to
142-
annotate public symbols
143-
- `--include-header` specifies a local header file that will be added as a
144-
`#include` in the processed source files if needed. This would typically
145-
refer to the header file containing the export macro definition.
146-
- The first two `--extra-arg` arguments ensure that `PUBLIC_ABI` is always
147-
defined (differently for Windows and Linux), and suppress the warning emitted
148-
if it already is. These arguments ensure the `PUBLIC_ABI` annotation is not
149-
mistakenly added to a symbol that already has it.
150-
- The third `--extra-arg` argument is Windows-specific and ensures that
151-
templates are always expanded while parsing. It is ensures overloaded private
152-
methods get properly exported when referenced only from inline templates.
153-
- The trailing positional arguments are the names of source files for IDS to
154-
scan.
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)