@@ -9,19 +9,24 @@ include the file will be recompiled and sometime it takes a lot of time.
99* [ Examples] ( #examples )
1010* [ Settings] ( #setting )
1111 * [ All arguments] ( #all-arguments )
12+ * [ report] ( #report )
13+ * [ unresolved] ( #unresolved )
14+ * [ most_impact] ( #most_impact )
15+ * [ unincluded] ( #unincluded )
16+ * [ different_type] ( #different_type )
1217 * [ configuration_file] ( #configuration_file )
18+ * [ compile_commands] ( #compile_commands )
1319 * [ project_dir] ( #project_dir )
1420 * [ file_extensions] ( #file_extensions )
1521 * [ analyze_without_extension] ( #analyze_without_extension )
1622 * [ include_dirs] ( #include_dirs )
1723 * [ ignore_dirs] ( #ignore_dirs )
1824 * [ ignore_system_includes] ( #ignore_system_includes )
1925 * [ ignore_files] ( #ignore_files )
20- * [ report] ( #report )
2126 * [ report_limit] ( #report_limit )
2227 * [ report_details_limit] ( #report_details_limit )
2328* [ Build] ( #build )
24- * [ Presentations] ( #presentation )
29+ * [ Presentations] ( #presentations )
2530* [ Tips for optimization includes] ( #tips-for-optimization-includes )
2631* [ Third-party libraries] ( #third-party-libraries )
2732* [ Support] ( #support )
@@ -97,15 +102,16 @@ See more examples in [docs/examples/](docs/examples/)
97102
98103Name|Short description
99104------------ | -------------
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 ) )
100106--[ 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)
101108--[ project_dir] ( #project_dir ) =dir|Project directory
102109--[ file_extensions] ( #file_extensions ) =arg1,arg2,...|Extensions C++ files (default: \* .cpp, \* .hpp,\* .c,\* .h,\* .cxx,\* .hxx)
103110--[ analyze_without_extension] ( #analyze_without_extension ) =true|Analyze files without extension (default: false)
104111--[ include_dirs] ( #include_dirs ) =dir1,dir2,...|Include directories
105112--[ ignore_dirs] ( #ignore_dirs ) =dir1,dir2,...|Directories that will be ignored
106113--[ ignore_system_includes] ( #ignore_system_includes ) =true|Ignore headers in \<\> (default: false)
107114--[ ignore_files] ( #ignore_files ) =regexp1,regexp2,...|Files will be ignored by regexp
108- --[ report] ( #report ) =name1,name2,...|List reports (default: unresolved,most_impact)
109115--[ report_limit] ( #report_limit ) =42|Maximum elements in report, 0 - unlimited (default: 10)
110116--[ report_details_limit] ( #report_details_limit ) =42|Maximum details in report, 0 - unlimited (default: 10)
111117--[ show_std_files] ( #show_std_files ) |Show standard library headers in output (default: false)
@@ -125,6 +131,27 @@ For example:
125131
126132[ Back to top] ( #cppinclude )
127133
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+
128155### project_dir
129156
130157Path to folder with sources. Often source files are located in * src* or
@@ -252,16 +279,172 @@ or in arguments:
252279Name of report. Possible values:
253280
254281* * 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 "..." .
258285
259286```
260287cppinclude --report=unresolved
261288cppinclude --report=most_impact
262289cppinclude --report=unresolved,most_impact
263290```
264291
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+
265448[ Back to top] ( #cppinclude )
266449
267450### report_limit
@@ -271,6 +454,14 @@ only 5 unresolved files will be in report:
271454
272455` cppinclude --report=unresolved --report_limit=5 `
273456
457+ Also you can set in configuration file:
458+
459+ ``` json
460+ {
461+ "report_limit" : 5
462+ }
463+ ```
464+
274465[ Back to top] ( #cppinclude )
275466
276467### report_details_limit
@@ -280,14 +471,30 @@ For example, only 3 files will be in report that include unresolved file
280471
281472` cppinclude --report=unresolved --report_details_limit=3 `
282473
474+ Also you can set in configuration file:
475+
476+ ``` json
477+ {
478+ "report_details_limit" : 3
479+ }
480+ ```
481+
283482[ Back to top] ( #cppinclude )
284483
285484### show_std_files
286485
287- Show standard library headers in output.
486+ Enable showing standard library headers in output.
288487
289488` cppinclude --show_std_files=true `
290489
490+ Also you can set in configuration file:
491+
492+ ``` json
493+ {
494+ "show_std_files" : true
495+ }
496+ ```
497+
291498[ Back to top] ( #cppinclude )
292499
293500## Build
@@ -319,6 +526,9 @@ on Unix:
319526
320527## Presentations
321528
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 )
322532* 2020, internal talk - [ 2020_internal_talk.pdf] ( docs/slides/2020_internal_talk.pdf )
323533
324534[ Back to top] ( #cppinclude )
0 commit comments