Summary: Glorious, glorious man pages. This changes a bunch of things that were hard to break up from the diff, so the resulting diff is big. Use `Cmdliner.Manpage` to format man pages (and also format a bit ourselves since it is so stubborn). As a bonus, introduce the following subcommands: ``` infer run ... # same as default mode with -- before infer capture ... # -a capture infer compile ... # -a compile infer analyze ... # InferAnalyze infer report ... # InferPrint infer diff ... # this one is not new infer clang ... # InferClang, not that you should use it ``` The man pages can still be improved a lot. Notable missing sections: `ENVIRONMENT`, stuff about .inferconfig, some example usage, `DESCRIPTION`, ... Reviewed By: jberdine Differential Revision: D4921083 fbshipit-source-id: 9602230master
Jules Villard
8 years ago
committed by
Facebook Github Bot
parent
ebd5ec0013
commit
709376945f
@ -0,0 +1,272 @@
|
|||||||
|
(*
|
||||||
|
* Copyright (c) 2017 - present Facebook, Inc.
|
||||||
|
* All rights reserved.
|
||||||
|
*
|
||||||
|
* This source code is licensed under the BSD style license found in the
|
||||||
|
* LICENSE file in the root directory of this source tree. An additional grant
|
||||||
|
* of patent rights can be found in the PATENTS file in the same directory.
|
||||||
|
*)
|
||||||
|
open! IStd
|
||||||
|
|
||||||
|
module CLOpt = CommandLineOption
|
||||||
|
|
||||||
|
type data = { long: string; command_doc: CLOpt.command_doc }
|
||||||
|
|
||||||
|
let inferconfig_env_var = "INFERCONFIG"
|
||||||
|
|
||||||
|
(** Name of the infer configuration file *)
|
||||||
|
let inferconfig_file = ".inferconfig"
|
||||||
|
|
||||||
|
let command_to_long = CLOpt.[
|
||||||
|
Analyze, "analyze"; Capture, "capture"; Clang, "clang"; Compile, "compile"; Report, "report";
|
||||||
|
ReportDiff, "reportdiff"; Run, "run";
|
||||||
|
]
|
||||||
|
|
||||||
|
let long_of_command =
|
||||||
|
List.Assoc.find_exn ~equal:CLOpt.equal_command command_to_long
|
||||||
|
|
||||||
|
let exe_name_of_command cmd =
|
||||||
|
let long = long_of_command cmd in
|
||||||
|
(* InferClang is special because it's not really a user-facing executable *)
|
||||||
|
if CLOpt.equal_command cmd CLOpt.Clang then "InferClang"
|
||||||
|
else "infer-" ^ long
|
||||||
|
|
||||||
|
let mk_command_doc ~see_also:see_also_commands ?and_also ?environment:environment_opt
|
||||||
|
?files:files_opt ~synopsis =
|
||||||
|
let section = 1 in
|
||||||
|
let see_also =
|
||||||
|
let exe_names = List.map see_also_commands ~f:(fun cmd ->
|
||||||
|
let exe = exe_name_of_command cmd in
|
||||||
|
Printf.sprintf "$(b,%s)(%d)" (Cmdliner.Manpage.escape exe) section) in
|
||||||
|
let suffix = match and_also with None -> "" | Some msg -> " " ^ msg in
|
||||||
|
[`P (String.concat ~sep:", " exe_names ^ suffix)] in
|
||||||
|
let environment = Option.value environment_opt
|
||||||
|
~default:[`I (Printf.sprintf "$(b,%s), $(b,%s), $(b,%s)"
|
||||||
|
CLOpt.args_env_var inferconfig_env_var CLOpt.strict_mode_env_var,
|
||||||
|
Printf.sprintf "See the %s section in the manual of $(b,infer)(%d)."
|
||||||
|
Cmdliner.Manpage.s_environment section)] in
|
||||||
|
let files = Option.value files_opt
|
||||||
|
~default:[`I (Printf.sprintf "$(b,%s)" inferconfig_file,
|
||||||
|
Printf.sprintf "See the %s section in the manual of $(b,infer)(%d)."
|
||||||
|
Cmdliner.Manpage.s_files section)] in
|
||||||
|
CLOpt.mk_command_doc ~section ~version:Version.versionString
|
||||||
|
~date:Version.man_pages_last_modify_date ~synopsis:[`Pre synopsis] ~environment ~files ~see_also
|
||||||
|
|
||||||
|
let analyze =
|
||||||
|
mk_command_doc ~title:"Infer Analysis"
|
||||||
|
~short_description:"analyze the files captured by infer"
|
||||||
|
~synopsis:"$(b,infer) $(b,analyze) $(i,[options])\n\
|
||||||
|
$(b,infer) $(i,[options])"
|
||||||
|
~description:[`P "Analyze the files captured in the project results directory and report."]
|
||||||
|
~see_also:CLOpt.[Report; Run]
|
||||||
|
|
||||||
|
let capture =
|
||||||
|
mk_command_doc ~title:"Infer Compilation Capture"
|
||||||
|
~short_description:"capture source files for later analysis"
|
||||||
|
~synopsis:"$(b,infer) $(b,capture) $(i,[options]) $(b,--) $(b,buck) $(i,...)\n\
|
||||||
|
$(b,infer) $(b,capture) $(b,--flavors) $(i,[options]) $(b,--) $(b,buck) $(i,...)\n\
|
||||||
|
$(b,infer) $(b,capture) $(b,--buck-compilation-database) $(i,[no-]deps) \
|
||||||
|
$(i,[options]) $(b,--) $(b,buck) $(i,...)\n\
|
||||||
|
$(b,infer) $(b,capture) $(i,[options]) $(b,--compilation-database) $(i,file)\n\
|
||||||
|
$(b,infer) $(b,capture) $(i,[options]) $(b,--compilation-database-escaped) \
|
||||||
|
$(i,file)\n\
|
||||||
|
$(b,infer) $(b,capture) $(i,[options]) $(b,--) $(b,gradle)/$(b,gradlew) \
|
||||||
|
$(i,...)\n\
|
||||||
|
$(b,infer) $(b,capture) $(i,[options]) $(b,--) $(b,javac) $(i,...)\n\
|
||||||
|
$(b,infer) $(b,capture) $(i,[options]) $(b,--) $(b,make)/$(b,clang)/$(b,gcc) \
|
||||||
|
$(i,...)\n\
|
||||||
|
$(b,infer) $(b,capture) $(i,[options]) $(b,--) $(b,mvn)/$(b,mvnw) \
|
||||||
|
$(i,...)\n\
|
||||||
|
$(b,infer) $(b,capture) $(i,[options]) $(b,--) $(b,ndk-build) $(i,...)\n\
|
||||||
|
$(b,infer) $(b,capture) $(i,[--no-xcpretty]) $(i,[options]) $(b,--) \
|
||||||
|
$(b,xcodebuild) $(i,...)"
|
||||||
|
~description:[
|
||||||
|
`P "Capture the build command or compilation database specified on the command line: infer \
|
||||||
|
intercepts calls to the compiler to read source files, translate them into infer's \
|
||||||
|
intermediate representation, and store the result of the translation in the results \
|
||||||
|
directory.";
|
||||||
|
]
|
||||||
|
~see_also:CLOpt.[Analyze;Compile;Run]
|
||||||
|
|
||||||
|
let clang =
|
||||||
|
mk_command_doc ~title:"Infer Clang Capture"
|
||||||
|
~short_description:"internal tool to capture clang commands"
|
||||||
|
~synopsis:"$(b,InferClang) $(i,[clang options])"
|
||||||
|
~description:[`P "This is used internally by other infer commands. You shouldn't need to call \
|
||||||
|
this directly."]
|
||||||
|
~options:[`P "Accepts the same command line options as $(b,clang)(1) (but still reads infer \
|
||||||
|
options from the environment)."]
|
||||||
|
~see_also:CLOpt.[Capture]
|
||||||
|
|
||||||
|
let compile =
|
||||||
|
mk_command_doc ~title:"Infer Project Compilation"
|
||||||
|
~short_description:"compile project from within the infer environment"
|
||||||
|
~synopsis:"$(b,infer) $(b,compile) $(b,--) $(i,[compile command])"
|
||||||
|
~description:[
|
||||||
|
`P "Intercepts compilation commands similarly to $(b,infer-capture), but simply execute \
|
||||||
|
these compilation commands and do not perform any translation of the source files. This \
|
||||||
|
can be useful to configure build systems or for debugging purposes.";
|
||||||
|
]
|
||||||
|
~examples:[
|
||||||
|
`P "$(b,cmake)(1) hardcodes the absolute paths to the compiler inside the Makefiles it \
|
||||||
|
generates, which defeats the later capture of compilation commands by infer. Thus, to \
|
||||||
|
capture a CMake project, one should configure the project from within the infer build \
|
||||||
|
environment, for instance:";
|
||||||
|
`Pre " \
|
||||||
|
mkdir build && cd build\n \
|
||||||
|
infer compile -- cmake ..\n \
|
||||||
|
infer capture -- make";
|
||||||
|
`P "The same solution can be used for projects whose \"./configure\" script hardcodes the \
|
||||||
|
paths to the compilers, for instance:";
|
||||||
|
`Pre " \
|
||||||
|
infer compile -- ./configure\n \
|
||||||
|
infer capture -- make";
|
||||||
|
`P "Another solution for CMake projects is to use CMake's compilation databases, for \
|
||||||
|
instance:";
|
||||||
|
`Pre " \
|
||||||
|
mkdir build && cd build\n \
|
||||||
|
cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1 ..\n \
|
||||||
|
infer capture --compilation-database compile_commands.json";
|
||||||
|
]
|
||||||
|
~see_also:CLOpt.[Capture]
|
||||||
|
|
||||||
|
let infer = mk_command_doc ~title:"Infer Static Analyzer"
|
||||||
|
~short_description:"static analysis for Java and C/C++/Objective-C/Objective-C++"
|
||||||
|
~synopsis:"$(b,infer) $(b,analyze) $(i,[options])\n\
|
||||||
|
$(b,infer) $(b,capture) $(i,[options])\n\
|
||||||
|
$(b,infer) $(b,compile) $(i,[options])\n\
|
||||||
|
$(b,infer) $(b,report) $(i,[options])\n\
|
||||||
|
$(b,infer) $(b,reportdiff) $(i,[options])\n\
|
||||||
|
$(b,infer) $(b,run) $(i,[options])\n\
|
||||||
|
$(b,infer) $(b,--compilation-database[-escaped]) $(i,file) $(i,[options])\n\
|
||||||
|
$(b,infer) $(i,[options]) $(b,--) $(b,compile command)\n\
|
||||||
|
$(b,infer) $(i,[options])"
|
||||||
|
~description:[
|
||||||
|
`P "Infer is a static analyzer. Given a collection of source files written in Java or in \
|
||||||
|
languages of the C family, and a command to build them, infer produces a list of \
|
||||||
|
potential issues.";
|
||||||
|
`P "Infer consists of a collection of tools referenced in the $(i,SEE ALSO) section of this \
|
||||||
|
manual. See their respective manuals for more information about each.";
|
||||||
|
]
|
||||||
|
~options:[
|
||||||
|
`P "If a compilation command is specified via the $(b,--) option or one of the \
|
||||||
|
$(b,--clang-compilation-database[-escaped]) options, $(b,infer) behaves as \
|
||||||
|
$(b,infer-run)(1). Otherwise, $(b,infer) behaves as $(b,infer-analyze)(1).";
|
||||||
|
`P "See the manuals of individual infer commands for details about their supported options.";
|
||||||
|
`P "Every infer command accepts the arguments from all the other infer commands. The same \
|
||||||
|
option may affect and thus be list in the manual of several commands.";
|
||||||
|
`P (Printf.sprintf
|
||||||
|
"Options are read from the $(b,%s) file, then from the $(b,%s) environment variable, \
|
||||||
|
then from the command line. Options in $(b,%s) take precedence over options in \
|
||||||
|
$(b,%s), and options passed on the command line take precedence over options in \
|
||||||
|
$(b,%s). See the $(i,%s) and $(i,%s) sections of this manual for more information."
|
||||||
|
inferconfig_file CLOpt.args_env_var
|
||||||
|
CLOpt.args_env_var
|
||||||
|
inferconfig_file
|
||||||
|
CLOpt.args_env_var Cmdliner.Manpage.s_environment Cmdliner.Manpage.s_files
|
||||||
|
);
|
||||||
|
]
|
||||||
|
~environment:[
|
||||||
|
`P (Printf.sprintf
|
||||||
|
"Extra arguments may be passed to all infer commands using the $(b,%s) \
|
||||||
|
environment variable (see the $(i,%s) section). $(b,%s) is expected to contain a \
|
||||||
|
string of %c-separated options. For instance, calling `%s=--debug^--print-logs infer` \
|
||||||
|
is equivalent to calling `infer --debug --print-logs`."
|
||||||
|
CLOpt.args_env_var
|
||||||
|
Cmdliner.Manpage.s_options CLOpt.args_env_var
|
||||||
|
CLOpt.env_var_sep CLOpt.args_env_var
|
||||||
|
);
|
||||||
|
`P (Printf.sprintf
|
||||||
|
"$(b,%s): Tells infer where to find the %s file. (See the %s section)"
|
||||||
|
inferconfig_env_var inferconfig_file Cmdliner.Manpage.s_files
|
||||||
|
);
|
||||||
|
`P (Printf.sprintf
|
||||||
|
"If $(b,%s) is set to \"1\", then infer commands will exit with an error code in some \
|
||||||
|
cases when otherwise a simple warning would be emitted on stderr, for instance if a \
|
||||||
|
deprecated form of an option is used."
|
||||||
|
CLOpt.strict_mode_env_var
|
||||||
|
);
|
||||||
|
]
|
||||||
|
~files:[
|
||||||
|
`P (Printf.sprintf
|
||||||
|
"$(b,%s) can be used to store infer options. Its format is that of a JSON \
|
||||||
|
record, where fields are infer long-form options, without their leading \"--\", and \
|
||||||
|
values depend on the type of the option:" inferconfig_file);
|
||||||
|
`Noblank;
|
||||||
|
`P "- for switches options, the value is a JSON boolean (true or false, without quotes)";
|
||||||
|
`Noblank;
|
||||||
|
`P "- for integers, the value is a JSON integer (without quotes)";
|
||||||
|
`Noblank;
|
||||||
|
`P "- string options have string values";
|
||||||
|
`Noblank;
|
||||||
|
`P (Printf.sprintf "- path options have string values, and are interpreted relative to the \
|
||||||
|
location of the %s file" inferconfig_file);
|
||||||
|
`Noblank;
|
||||||
|
`P "- cumulative options are JSON arrays of the appropriate type";
|
||||||
|
`P (Printf.sprintf "Infer will look for an $(b,%s) file in the current directory, then its \
|
||||||
|
parent, etc., stopping at the first $(b,%s) file found."
|
||||||
|
inferconfig_file inferconfig_file);
|
||||||
|
`P "Example:";
|
||||||
|
`Pre " {\
|
||||||
|
\n \"cxx\": false,\
|
||||||
|
\n \"infer-blacklist-files-containing\": [\"@generated\",\"@Generated\"]\
|
||||||
|
\n }";
|
||||||
|
]
|
||||||
|
~see_also:(List.filter ~f:(function | CLOpt.Clang -> false | _ -> true) CLOpt.all_commands)
|
||||||
|
~and_also:", $(b,inferTraceBugs)"
|
||||||
|
"infer"
|
||||||
|
|
||||||
|
let report =
|
||||||
|
mk_command_doc ~title:"Infer Reporting"
|
||||||
|
~short_description:"compute and manipulate infer results"
|
||||||
|
~synopsis:"$(b,infer) $(b,report) $(i,[options]) [$(i,file.specs)...]"
|
||||||
|
~description:[
|
||||||
|
`P "Read, convert, and print .specs files in the results directory. Each spec is printed to \
|
||||||
|
standard output unless option -q is used.";
|
||||||
|
`P "If no specs file are passed on the command line, process all the .specs in the results \
|
||||||
|
directory.";
|
||||||
|
]
|
||||||
|
~see_also:CLOpt.[ReportDiff; Run]
|
||||||
|
|
||||||
|
let reportdiff =
|
||||||
|
mk_command_doc ~title:"Infer Report Difference"
|
||||||
|
~short_description:"compute the differences between two infer reports"
|
||||||
|
~synopsis:"$(b,infer) $(b,reportdiff) $(b,--report-current) $(i,file) \
|
||||||
|
$(b,--report-previous) $(i,file) $(i,[options])"
|
||||||
|
~description:[
|
||||||
|
`P "Given two infer reports $(i,previous) and $(i,current), compute the following three \
|
||||||
|
reports and store them inside the \"differential/\" subdirectory of the results \
|
||||||
|
directory:";
|
||||||
|
`Noblank; `P "- $(b,introduced.json) contains the issues found in $(i,current) but not \
|
||||||
|
$(i,previous);";
|
||||||
|
`Noblank; `P "- $(b,fixed.json) contains the issues found in $(i,previous) but not \
|
||||||
|
$(i,current);";
|
||||||
|
`Noblank; `P "- $(b,preexisting.json) contains the issues found in both $(i,previous) and \
|
||||||
|
$(i,current).";
|
||||||
|
`P "All three files follow the same format as normal infer reports.";
|
||||||
|
]
|
||||||
|
~see_also:CLOpt.[Report]
|
||||||
|
|
||||||
|
let run =
|
||||||
|
mk_command_doc ~title:"Infer Analysis of a Project"
|
||||||
|
~short_description:"capture source files, analyze, and report"
|
||||||
|
~synopsis:"$(b,infer) $(b,run) $(i,[options])\n\
|
||||||
|
$(b,infer) $(i,[options]) $(b,--) $(i,compile command)"
|
||||||
|
~description:[
|
||||||
|
`P "Calling \"$(b,infer) $(b,run) $(i,[options])\" is equivalent to performing the following \
|
||||||
|
sequence of commands:";
|
||||||
|
`Pre "$(b,infer) $(b,capture) $(i,[options])\n\
|
||||||
|
$(b,infer) $(b,analyze) $(i,[options])";
|
||||||
|
]
|
||||||
|
~see_also:CLOpt.[Analyze; Capture; Report]
|
||||||
|
|
||||||
|
let command_to_data =
|
||||||
|
let mk cmd mk_doc =
|
||||||
|
let long = long_of_command cmd in
|
||||||
|
let command_doc = mk_doc (exe_name_of_command cmd) in
|
||||||
|
cmd, { long; command_doc } in
|
||||||
|
CLOpt.[mk Analyze analyze; mk Capture capture; mk Clang clang; mk Compile compile;
|
||||||
|
mk Report report; mk ReportDiff reportdiff; mk Run run]
|
||||||
|
|
||||||
|
let data_of_command command =
|
||||||
|
List.Assoc.find_exn ~equal:CLOpt.equal_command command_to_data command
|
||||||
@ -0,0 +1,19 @@
|
|||||||
|
(*
|
||||||
|
* Copyright (c) 2017 - present Facebook, Inc.
|
||||||
|
* All rights reserved.
|
||||||
|
*
|
||||||
|
* This source code is licensed under the BSD style license found in the
|
||||||
|
* LICENSE file in the root directory of this source tree. An additional grant
|
||||||
|
* of patent rights can be found in the PATENTS file in the same directory.
|
||||||
|
*)
|
||||||
|
open! IStd
|
||||||
|
|
||||||
|
module CLOpt = CommandLineOption
|
||||||
|
|
||||||
|
type data = { long: string; command_doc: CLOpt.command_doc }
|
||||||
|
|
||||||
|
val inferconfig_env_var : string
|
||||||
|
val inferconfig_file : string
|
||||||
|
|
||||||
|
val infer : CLOpt.command_doc
|
||||||
|
val data_of_command : CLOpt.command -> data
|
||||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
Loading…
Reference in new issue