@@ -9,19 +9,24 @@ include the file will be recompiled and sometime it takes a lot of time.
9
9
* [ Examples] ( #examples )
10
10
* [ Settings] ( #setting )
11
11
* [ All arguments] ( #all-arguments )
12
+ * [ report] ( #report )
13
+ * [ unresolved] ( #unresolved )
14
+ * [ most_impact] ( #most_impact )
15
+ * [ unincluded] ( #unincluded )
16
+ * [ different_type] ( #different_type )
12
17
* [ configuration_file] ( #configuration_file )
18
+ * [ compile_commands] ( #compile_commands )
13
19
* [ project_dir] ( #project_dir )
14
20
* [ file_extensions] ( #file_extensions )
15
21
* [ analyze_without_extension] ( #analyze_without_extension )
16
22
* [ include_dirs] ( #include_dirs )
17
23
* [ ignore_dirs] ( #ignore_dirs )
18
24
* [ ignore_system_includes] ( #ignore_system_includes )
19
25
* [ ignore_files] ( #ignore_files )
20
- * [ report] ( #report )
21
26
* [ report_limit] ( #report_limit )
22
27
* [ report_details_limit] ( #report_details_limit )
23
28
* [ Build] ( #build )
24
- * [ Presentations] ( #presentation )
29
+ * [ Presentations] ( #presentations )
25
30
* [ Tips for optimization includes] ( #tips-for-optimization-includes )
26
31
* [ Third-party libraries] ( #third-party-libraries )
27
32
* [ Support] ( #support )
@@ -97,15 +102,16 @@ See more examples in [docs/examples/](docs/examples/)
97
102
98
103
Name|Short description
99
104
------------ | -------------
105
+ --[ report] ( #report ) =name1,name2,...|List reports. Name of reports: [ unresolved] ( #unresolved ) , [ most_impact] ( #most_impact ) , [ unincluded] ( #unincluded ) , [ different_type] ( #different_type ) (default: [ unresolved] ( #unresolved ) ,[ most_impact] ( #most_impact ) ,[ unincluded] ( #unincluded ) )
100
106
--[ configuration_file] ( #configuration_file ) =file|Path to configuration file (default: .cppinclude.json)
107
+ --[ compile_commands] ( #compile_commands ) =file|Path to JSON Compilation Database (default: compile_commands.json)
101
108
--[ project_dir] ( #project_dir ) =dir|Project directory
102
109
--[ file_extensions] ( #file_extensions ) =arg1,arg2,...|Extensions C++ files (default: \* .cpp, \* .hpp,\* .c,\* .h,\* .cxx,\* .hxx)
103
110
--[ analyze_without_extension] ( #analyze_without_extension ) =true|Analyze files without extension (default: false)
104
111
--[ include_dirs] ( #include_dirs ) =dir1,dir2,...|Include directories
105
112
--[ ignore_dirs] ( #ignore_dirs ) =dir1,dir2,...|Directories that will be ignored
106
113
--[ ignore_system_includes] ( #ignore_system_includes ) =true|Ignore headers in \<\> (default: false)
107
114
--[ ignore_files] ( #ignore_files ) =regexp1,regexp2,...|Files will be ignored by regexp
108
- --[ report] ( #report ) =name1,name2,...|List reports (default: unresolved,most_impact)
109
115
--[ report_limit] ( #report_limit ) =42|Maximum elements in report, 0 - unlimited (default: 10)
110
116
--[ report_details_limit] ( #report_details_limit ) =42|Maximum details in report, 0 - unlimited (default: 10)
111
117
--[ show_std_files] ( #show_std_files ) |Show standard library headers in output (default: false)
@@ -125,6 +131,27 @@ For example:
125
131
126
132
[ Back to top] ( #cppinclude )
127
133
134
+ ### compile_commands
135
+
136
+ Path to generated * compile_commands.json* file by CMake with argument
137
+ * -DCMAKE_EXPORT_COMPILE_COMMANDS=ON* , for example:
138
+
139
+ ` cmake .. -DCMAKE_EXPORT_COMPILE_COMMANDS=ON `
140
+
141
+ You can set path in configuration file:
142
+
143
+ ``` json
144
+ {
145
+ "compile_commands" : " build/compile_commands.json"
146
+ }
147
+ ```
148
+
149
+ or in arguments:
150
+
151
+ ` cppinclude --compile_commands=build/compile_commands.json `
152
+
153
+ [ Back to top] ( #cppinclude )
154
+
128
155
### project_dir
129
156
130
157
Path to folder with sources. Often source files are located in * src* or
@@ -252,16 +279,172 @@ or in arguments:
252
279
Name of report. Possible values:
253
280
254
281
* * unresolved* -- show included files that are not found in project folder;
255
- * * most_impact* -- show files that most impact on other files.
256
-
257
- This report show how many files will be recompiled if the file is changes
282
+ * * most_impact* -- show files that most impact on other files;
283
+ * * unincluded * -- show unincluded headers;
284
+ * * different_type * -- show headers that are included in #include <...> and #include "..." .
258
285
259
286
```
260
287
cppinclude --report=unresolved
261
288
cppinclude --report=most_impact
262
289
cppinclude --report=unresolved,most_impact
263
290
```
264
291
292
+ Also you can set in configuration file:
293
+
294
+ ``` json
295
+ {
296
+ "report" : [ " unresolved" , " most_impact" ]
297
+ }
298
+ ```
299
+
300
+ [ Back to top] ( #cppinclude )
301
+
302
+ #### unresolved
303
+
304
+ Show files that are found in includes but didn't found in file system.
305
+ One of the resean is missing includes files, for example:
306
+ There is file * main.cpp* , folder * include* that store file * header.hpp* :
307
+
308
+ ```
309
+ tree
310
+ .
311
+ ├── include
312
+ │ └── header.hpp
313
+ └── main.cpp
314
+
315
+ ```
316
+
317
+ If run * cppinclude* result will be:
318
+
319
+ ```
320
+ cppinclude --report=unresolved
321
+ Start initialization project ...
322
+ Start analyze sources ...
323
+ Start report results ...
324
+ Unresolved files:
325
+ 1. "header.hpp" isn't resolved in:
326
+ 1. "main.cpp" line: 1
327
+
328
+ ```
329
+
330
+ But if add folder * include* to * include_dirs* resultat will be empty:
331
+
332
+ ```
333
+ cppinclude --report=unresolved --include_dirs=include
334
+ ```
335
+
336
+ [ Back to top] ( #cppinclude )
337
+
338
+ #### most_impact
339
+
340
+ Show how many files will be recompiled with header will be changed.
341
+ Example from [ docs/examples/simple_example/] ( docs/examples/simple_example/ )
342
+
343
+ ```
344
+ cppinclude --report=most_impact
345
+ ...
346
+ Most impact files:
347
+ 1 : "char_kind.hpp" impact on 11 file(s)
348
+ Included by:
349
+ 1 : "base_char.hpp" line 3, impact on 10 file(s)
350
+ 2 : "base_char.hpp" impact on 10 file(s)
351
+ Included by:
352
+ 1 : "base_char_factory.hpp" line 3, impact on 5 file(s)
353
+ 2 : "char_a.hpp" line 3, impact on 2 file(s)
354
+ 3 : "char_b.hpp" line 3, impact on 2 file(s)
355
+ 3 : "base_char_factory.hpp" impact on 5 file(s)
356
+ Included by:
357
+ 1 : "char_a_factory.hpp" line 3, impact on 2 file(s)
358
+ 2 : "char_b_factory.hpp" line 3, impact on 2 file(s)
359
+ ...
360
+ ```
361
+
362
+ It means if file char_kind.hpp will be changed 11 files are recompiled.
363
+
364
+ [ Back to top] ( #cppinclude )
365
+
366
+ #### unincluded
367
+
368
+ Show files that are found in file system but didn't found in includes.
369
+ It often happens after refactoring when file that include header was deleted.
370
+ Example from [ docs/examples/simple_example_with_unincluded_headers/] ( docs/examples/simple_example_with_unincluded_headers/ )
371
+
372
+ ```
373
+ cppinclude --report=unincluded
374
+ Start initialization project ...
375
+ Start analyze sources ...
376
+ Start report results ...
377
+ Unincluded headers:
378
+ 1 : "config.hpp"
379
+ 2 : "settings.hpp"
380
+
381
+ ```
382
+
383
+ ** Limitations:**
384
+
385
+ * Header with same names:
386
+
387
+ If headers have same name but are located in different folders will be found
388
+ only first header and other will be unincluded.
389
+ For example: * lib1/header.hpp* , * lib2/header.hpp* and
390
+ * main.cpp* :
391
+
392
+ ``` c++
393
+ #include " header.hpp"
394
+ ...
395
+ ```
396
+ Result will be:
397
+
398
+ ```
399
+ cppinclude --include_dirs=lib1,lib2 --report=unincluded
400
+
401
+ Start initialization project ...
402
+ Start analyze sources ...
403
+ Start report results ...
404
+ Unincluded headers:
405
+ 1 : "lib2/header.hpp"
406
+
407
+ ```
408
+
409
+ * Empty result for CMake project:
410
+
411
+ If analyze CMake project ( generated file compile_commands.json )
412
+ result will be empty. Because in current implementation * cppinclude* analyze
413
+ source files on file system or files from compile_commands.json
414
+
415
+ * Header files are files that have extension started with * h* letter
416
+
417
+ *** All limitations will be fixed in future releases ** *
418
+
419
+
420
+ [ Back to top] ( #cppinclude )
421
+
422
+ #### different_type
423
+
424
+ Show headers that are included in different ways.
425
+ It helps to follow code style in project,
426
+ for example include third party libraries in <...> and project header in "...".
427
+ Example from [ docs/examples/simple_example_for_different_type_report/] ( docs/examples/simple_example_for_different_type_report/ )
428
+
429
+ ```
430
+ cppinclude --report=different_type
431
+ Start initialization project ...
432
+ Start analyze sources ...
433
+ Start report results ...
434
+ Files that are included by different ways:
435
+ 1. base_char.hpp
436
+ With double quotation marks ( #include "..." ) in files:
437
+ 1. base_char_factory.hpp line 3
438
+ 2. char_b.hpp line 3
439
+ With angle brackets ( #include <...> ) in files:
440
+ 1. char_a.hpp line 3
441
+ 2. base_char_factory.hpp
442
+ With double quotation marks ( #include "..." ) in files:
443
+ 1. char_b_factory.hpp line 3
444
+ With angle brackets ( #include <...> ) in files:
445
+ 1. char_a_factory.hpp line 3
446
+ ```
447
+
265
448
[ Back to top] ( #cppinclude )
266
449
267
450
### report_limit
@@ -271,6 +454,14 @@ only 5 unresolved files will be in report:
271
454
272
455
` cppinclude --report=unresolved --report_limit=5 `
273
456
457
+ Also you can set in configuration file:
458
+
459
+ ``` json
460
+ {
461
+ "report_limit" : 5
462
+ }
463
+ ```
464
+
274
465
[ Back to top] ( #cppinclude )
275
466
276
467
### report_details_limit
@@ -280,14 +471,30 @@ For example, only 3 files will be in report that include unresolved file
280
471
281
472
` cppinclude --report=unresolved --report_details_limit=3 `
282
473
474
+ Also you can set in configuration file:
475
+
476
+ ``` json
477
+ {
478
+ "report_details_limit" : 3
479
+ }
480
+ ```
481
+
283
482
[ Back to top] ( #cppinclude )
284
483
285
484
### show_std_files
286
485
287
- Show standard library headers in output.
486
+ Enable showing standard library headers in output.
288
487
289
488
` cppinclude --show_std_files=true `
290
489
490
+ Also you can set in configuration file:
491
+
492
+ ``` json
493
+ {
494
+ "show_std_files" : true
495
+ }
496
+ ```
497
+
291
498
[ Back to top] ( #cppinclude )
292
499
293
500
## Build
@@ -319,6 +526,9 @@ on Unix:
319
526
320
527
## Presentations
321
528
529
+ * 2020, Lightning Talk on CppCon 2020, cppinclude - Tool for analyzing includes in C++
530
+ * Video : [ https://www.youtube.com/watch?v=DXil_ahLTyg ] ( https://www.youtube.com/watch?v=DXil_ahLTyg )
531
+ * Slides: [ 2020_cppcon2020_small_talk.pdf] ( docs/slides/2020_cppcon2020_small_talk.pdf )
322
532
* 2020, internal talk - [ 2020_internal_talk.pdf] ( docs/slides/2020_internal_talk.pdf )
323
533
324
534
[ Back to top] ( #cppinclude )
0 commit comments