JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

CodeSonar® 9.2p0 CONFIDENTIAL CodeSecure Inc
General

Command Line Build/Analysis

For general information about building and analyzing CodeSonar projects, see section Building and Analyzing.

Note: The first time you build a project, you may need to accept the CodeSonar license.

Note: If User Account Control is enabled, your system may request permission for cs_uac_daemonize.exe from CodeSecure, Inc to continue. Click Continue to proceed.

The Command

Given the elements described below, the general form of the usual CodeSonar build/analysis command is:

codesonar analyze /path/to/pfiles-name
[-project [/[ancestors/]]proj-name] [-no-services] [-foreground] [-wait] [-clean] [-clean-backend] \
[-force-base-hub-analysis] [-name analysis-name] [-preset preset-name] [-no-default-presets] [-conf-file extra-conf-path] \
[-offline] [-property propkey propval] [-launchd-group ldgroup] [-launchd-key ldkey] \
[-watch-pid pid] [-watch-all-pids] \
[-auth authtype] [-hubuser username] [-hubpwfile pwfile] [-hubbearerfile bearerfile] [-hubcert certfile] [-hubkey privatekeyfile] \
[-remote analysis-launchd] [-remote-archive daemonmode-launchd] [-srcroot basedir] [[protocol://]host:port] [command]

This will build a project based on the underlying software build corresponding to command and any specified flags, and then perform the CodeSonar analysis and output the result to a hub, associating them with a CodeSonar project named proj-name (defaulting to pfiles-name if -project is not specified).

To accumulate project components without finalizing the project or running the analysis, use build instead of analyze.

Command Elements

The CodeSonar build/analysis command has several elements.

command The command that invokes your CodeSonar-facing build.
This is an extended variant of your normal software build that performs any additional steps required to inform CodeSonar of components to be included in the CodeSonar project. These additional steps depend on the language of the software to be analyzed. See the language-specific project build documentation for full details.
C and C++ the CodeSonar-facing build is the same as the regular software build.
Java the CodeSonar-facing build must invoke cs-java-scan after all Java compilations have taken place.
C# the CodeSonar-facing build must invoke cs-dotnet-scan after all C# compilations have taken place.
SARIF files
(and any associated tier 3 source files)		 the CodeSonar-facing build must invoke codesonar import_sarif.py after the SARIF file has been generated.
all other files the CodeSonar-facing build must invoke codesonar add_source_files.py.

If you have third-party analysis results for any language to include in the project, the CodeSonar-facing build must also invoke codesonar import_sarif.py on the relevant SARIF result files.

If command is missing, no building takes place and the analysis starts with the pre-existing contents of pfiles-name.prj_files (which will be a child of the project directory). If pfiles-name.prj_files is empty or missing, an error is raised.
build-command Specifies how far the CodeSonar project build/analysis should proceed. The options are
analyze Build the project (if necessary), analyze it, and send the results to the hub. For most users, analyze is the only build-command that will ever be needed.
build Accumulate components toward a project, but do not build or analyze it.
/path/to/pfiles-name Identifies the project directory, and provides a basis for naming files and subdirectories in that directory. In the absence of a -project proj-name argument, also provides the project name.
  • pfiles-name is used to construct various file names in the project directory.

    If -project arg is not specified, pfiles-name is also used as the project name, used to identify the project to the hub. See Hub Project Identification: Examples below for annotated example command lines with and without -project.

  • /path/to/ is the file system path to the project directory, which CodeSonar will use to store a number of files related to the analysis. Many of the file names will be based on pfiles-name, so make sure you chose one that will not lead to name conflicts with your existing files. See Troubleshooting Build for a full list of the files and directories that will be written.

    You must have write access to the project build directory, otherwise CodeSonar will not be able to write these project files. Windows users should specify a directory located outside the Program Files directory tree.

  • The project build directory will be /path/to/pfiles-name.prj_files.
    For local-managed analyses (those that do not specify -remote analysis-launchd), this will also be the project analysis directory.
[-remote analysis-launchd] Specifies that the CodeSonar analysis should be managed remotely, using analysis launch daemon analysis-launchd. The argument analysis-launchd is interpreted as follows.
positive integer N all launch daemons that are transitive descendants of the launchd group whose LDGroup ID is N.
negative integer -M the single launch daemon whose Launch Daemon ID is M.
/Foo/Bar/* all launch daemons that are transitive descendants of the launchd group(s) whose LDGroup Path is /Foo/Bar/. Case sensitive.
/Foo/Bar/user@machine all launch daemons whose Parent LDGroup is Foo/Bar, System User is user, and Machine is machine. Case sensitive.

At least one launch daemon matching analysis-launchd must already be running. If multiple launch daemons matching analysis-launchd are running, the hub will select one of them to be the analysis launch daemon.

This option takes precedence over the REMOTE_ANALYSIS_LAUNCHD configuration parameter.

Recommended usage:

CodeSonar SaaS: Specify -remote "/saas/*" to instruct the SaaS hub to select a suitable launch daemon from its saas launchd group.
otherwise: Specify -remote analysis-launchd if you want to use a remote launch daemon (that is, a launch daemon that is associated with your hub, but does not have to be on the same machine that you are using to build the CodeSonar project).

Otherwise, the analysis will use a launch daemon whose Machine, System User, Hub User, and Installation match those that were used to invoke the analysis command. If such a launch daemon is not already running, CodeSonar will start one when you execute the analysis, failing if the Hub User does not have sufficient permissions.

For a step-by-step example, see Task: Set Up and Perform a Remote-Managed Analysis.

This option does not affect the CodeSonar build phase, which will always take place locally.

  • If you specify this option, any specified -launchd-group or -launchd-key options will have no effect on the analyze interval or daemon mode interval.
  • If you specify this option, -no-services will be ignored.
  • If you specify both -remote analysis-launchd and -foreground, the build/analysis will exit with an error. If you want the codesonar analyze process to wait to return until the analysis finishes, specify -wait.
  • If you are invoking CodeSonar from a continuous integration tool, specify exactly one of {-remote analysis-launchd, -foreground}.
  • If you specify both -remote analysis-launchd and -remote-archive archive-launchd, data and control will be transferred from analysis-launchd to archive-launchd when the analysis transitions to daemon mode.
    If you specify -remote analysis-launchd without specifying -remote-archive, analysis-launchd will remain the analysis launch daemon when the analysis transitions to daemon mode.
  • If you specify both -remote and -offline, the build/analysis will exit with an error. For more information, see the entry for -offline.
[-remote-archive archive-launchd] Specifies that when the CodeSonar analysis transitions to daemon mode, archive-launchd should become the analysis launch daemon.
  • The analysis directory is moved to a location under the home directory for archive-launchd.
  • Daemon mode is managed remotely.
The argument archive-launchd is interpreted as follows.
positive integer N all launch daemons that are transitive descendants of the launchd group whose LDGroup ID is N.
negative integer -M the single launch daemon whose Launch Daemon ID is M.
/Foo/Bar/* all launch daemons that are transitive descendants of the launchd group(s) whose LDGroup Path is /Foo/Bar/. Case sensitive.
/Foo/Bar/user@machine all launch daemons whose Parent LDGroup is Foo/Bar, System User is user, and Machine is machine. Case sensitive.
  • If multiple launch daemons matching archive-launchd are running, the hub will select one of them.
  • If no such launch daemons are running, the analysis launch daemon and analysis directory from the analysis phase are also used in daemon mode.

This option takes precedence over the REMOTE_DAEMON_LAUNCHD configuration parameter.

Recommended usage:

CodeSonar SaaS: Your command will already include -remote "/saas/*", so there is no need to specify a separate -remote-archive value.
otherwise: Specify -remote-archive archive-launchd if you want to use a remote analysis launch daemon when the analysis is in daemon mode and you want it to be different to the analysis launch daemon used in the analysis phase.

Otherwise, the analysis will have the same analysis launch daemon in daemon mode as it had in the analysis phase. This could be either local-managed or remote-managed, depending on how the remainder of the build/analysis is specified.

The main -remote-archive use case is for running the CodeSonar analysis within a continuous integration (CI) tool or containerized environment. In these contexts, the analysis directory may be deleted as part of standard cleanup once the build pipeline (or similar) finishes. Moving the analysis directory to a remote location when daemon mode commences ensures that analysis information remains available to the hub.

This option does not affect the CodeSonar build phase, which will always take place locally. It also does not affect the analysis phase, which is controlled by the -remote option.

  • If you specify this option, any specified -launchd-group or -launchd-key options will have no effect on the daemon mode interval.
  • If you specify this option, -no-services will be ignored.
  • If you specify both -remote-archive and -offline, the build/analysis will exit with an error. For more information, see the entry for -offline.
[-project [/[ancestors/]]proj-name] Specifies the project with which this analysis is associated on the hub.
  • proj-name is the project name, used to identify the project to the hub.
  • ancestors is the project's Ancestors string: a /-separated sequence of project tree names, representing the path from the root project tree to the project's parent project tree through the hub's overall project tree hierarchy. (Note that this does not entail correspondence with a file system path.)
    The leading / denotes the root project tree.
    • -project /myproj specifies a project named myproj whose parent project tree is the root project tree.
    • -project myproj specifies a project named myproj that may be located anywhere in the project tree hierarchy.
    • If you specify ancestors without a leading /, the build/analysis will fail.
  • Enclose multiple-word project names and project tree names in quote marks "".
For example, suppose a build/analysis command line specifies -project /siteA/"team X"/myproj. This specifies a project named myproj such that: The analysis will be associated with a hub project as follows.
  • If there is an existing hub project whose name matches proj-name and Ancestors match ancestors, and for which the authorizing hub user has PROJECT_ADD_CHILD permission, the analysis will be associated with that project. If there are multiple such projects, CodeSonar will choose one.
    If proj-name is specified without ancestors or leading /, the matching project may be located anywhere in the project tree hierarchy.
  • If there are no such projects, but ancestors corresponds to an existing path from the root project tree to a project tree T for which the authorizing hub user has PTREE_ADD_CHILD permission, CodeSonar will create a project named proj-name as a child of T. If there are multiple such paths, CodeSonar will choose one. If ancestors is not specified, these checks and operations are carried out with respect to the root project tree.
  • Otherwise, the analysis will fail.

If -project proj-name is not specified, the analysis will be associated with the project whose name matches the pfiles-name specified in the first argument to the analyze (or build) subcommand.

If you specify both -project and -offline, the build/analysis will exit with an error. For more information, see the entry for -offline.

See Hub Project Identification: Examples below for annotated example command lines with and without -project.

CodeSonar creates infrastructure for a new analysis on the hub when you start accumulating analysis files in /path/to/pfiles-name.prj_files/, and continues to associate with the same analysis until the accumulated components have been collected into /path/to/pfiles-name.prj and analyzed. In particular, this means that if you are accumulating components with one or more codesonar build commands before issuing a final codesonar analyze command, all these commands will be associated with the same analysis, and that analysis will be associated with the project specified (including by default) in the first of the build commands: -project arguments in subsequent build or analysis commands will have no effect.
[-no-services] [Windows only] Use this if you don't want to run the CodeSonar launch daemon as a Windows service.

Running with services is the default and is recommended unless services cause problems for the user. For more information, see section CodeSonar as a Windows Service.

Specifying USE_SERVICES=No in the project configuration file provides equivalent functionality.

If -remote analysis-launchd is specified, this option has no effect.

If you specify both -no-services and -offline, the build/analysis will exit with an error. For more information, see the entry for -offline.
[-foreground] When this is specified, the CodeSonar build/analysis will run in the foreground (otherwise it runs in the background). This can be useful if, for example, you are developing a CodeSonar plug-in and want to run from inside a debugger.
  • If you specify both -foreground and -remote analysis-launchd, the build/analysis will exit with an error.
  • If you specify both -foreground and -wait, the build/analysis will exit with an error.
  • If you are invoking CodeSonar from a continuous integration tool, specify exactly one of {-foreground, -wait}.

Specifying FOREGROUND=Yes in the project configuration file provides equivalent functionality.

When you specify this option, the analysis log is written to stdout. It is not recorded to the corresponding hub Analysis Log page.

The CodeSonar analysis will not implicitly start a launch daemon on behalf of a foreground analysis. For more information, see Letting codesonar analyze Start a Launch Daemon Implicitly.

Offline build/analysis always runs in the foreground, even if -foreground is not specified.

See also -wait.
[-wait] When this is specified, the codesonar analyze process will wait to return until one of the following occurs.
  • The analysis completes.
  • The analysis stalls.
  • The analysis launch daemon loses its connection to the hub.
    If you have specified a remote analysis launch daemon with -remote analysis-launchd, this can be on a different machine to the one on which the codesonar analyze process is running.
  • The codesonar analyze process loses its connection to the hub.
This can be useful in cases where subsequent commands wish to inspect the final analysis results.

See also -foreground.

  • The -wait option differs from -foreground in several ways.
    • It can be used in combination with -remote analysis-launchd.
    • The analysis log is recorded to the corresponding hub Analysis Log page. It is not written to stdout.
    • It is less robust against connectivity problems between the hub and the machine running codesonar analyze, or between the hub and the machine running the remote launch daemon specified with -remote analysis-launchd (if any).
  • If you specify both -foreground and -wait, the build/analysis will exit with an error.
  • If you are invoking CodeSonar from a continuous integration tool, specify exactly one of {-foreground, -wait}.

If you specify both -wait and -offline, the build/analysis will exit with an error. For more information, see the entry for -offline.
[-clean] When this is specified, all the CodeSonar internal representations for the project will be deleted from pfiles-name.prj_files before the build/analysis runs. A new set of internal representations will then be constructed, as specified by the remainder of the build/analysis command. The analysis will therefore be a base analysis.

In general, -clean will be used in combination with a full rebuild of the software: the observed command should be chosen accordingly.

If you are accumulating project components with a series of codesonar build commands, only specify -clean for the first one.

The deleted information includes any accumulated offline information. If you have offline information that you do not wish to discard, submit it with codesonar submit-results or make a copy of the analysis directory before running a command that specifies -clean.
[-clean-backend] When this is specified, analysis results and the internal representation for the finalized CodeSonar project—but not internal representations accumulated from the individual compilation unit or units in the analysis—will be deleted from pfiles-name.prj_files before the build/analysis runs. The analysis will therefore be a base analysis that incorporates the internal representation that remains in pfiles-name.prj_files along with any internal representations constructed as specified by the remainder of the build/analysis command.

It may be useful to think of -clean-backend as specifying that any codesonar analyze commands for which any results and output are still present in pfiles-name.prj_files should retroactively be treated as if they were codesonar build commands instead.

If you are accumulating project components with a series of codesonar build commands, only specify -clean-backend for the first one.

The only known use case for -clean-backend is plug-in development. Use -clean for all other situations where you want to perform a base analysis in an analysis directory previously used for incremental analysis.

The -clean option subsumes -clean-backend.
[-force-base-hub-analysis] If INCREMENTAL_BUILD=Yes, the build/analysis will be performed as usual for INCREMENTAL_BUILD=Yes, but will be reported to the hub as a new base analysis in all cases.
If INCREMENTAL_BUILD=No, this option has no effect.

This option is useful if you have an analysis directory for a parent analysis, but no longer have access to the hub on which the parent was analyzed. Note that if the build/analysis is incremental, only artifacts (warnings, metrics, files, and so forth) from the incremental portions of the project will be included in the analysis results. There is every possibility that these artifacts will represent a strict subset of those for the parent analysis. One consequence is that some links in the results for this analysis may be broken.

The only known use case for -force-base-hub-analysis is plug-in development. Use -clean for all other situations where you want to perform a base analysis in an analysis directory previously used for incremental analysis.

You can specify -force-base-hub-analysis for an offline build/analysis command: when the accumulated offline information is subsequently submitted to the hub it will be associated with a new base analysis.
[-name analysis-name] The analysis name will be set to analysis-name. Enclose multiple-word names in quote marks "". If you specify -name multiple times, the last name specified is used. The CodeSonar web GUI also provides functionality for changing the analysis name later.

This option takes precedence over the ANALYSIS_NAME configuration file parameter.

If you specify both -name and -offline, the build/analysis will exit with an error. For more information, see the entry for -offline.
[-preset preset-name] The configuration preset named preset-name will be applied to the CodeSonar build/analysis.

You can specify -preset preset-name multiple times in order to apply multiple presets. The presets will be applied in the order in which they were specified, along with any additional configuration files specified with -conf-file.

Configuration Files: Changing Parameter Settings discusses the issues to consider when you change parameter settings for a given project, including changes in preset files or in the set of presets applied. In particular, if you are performing a build/analysis in multiple stages (that is, one or more invocations of codesonar build followed by an invocation of codesonar analyze) and using -preset to apply any of the presets shipped with CodeSonar, specify the same set of presets in the same order for each stage.
[-no-default-presets] Specify -no-default-presets to run the build or analysis without invoking default configuration presets. Note: This flag can be used to ensure that two CodeSonar installations do not behave differently due to default presets.

Configuration Files: Changing Parameter Settings discusses the issues to consider when you change parameter settings for a given project, including changes in default preset files or in the set of default presets. In particular, if you are performing a build/analysis in multiple stages (that is, one or more invocations of codesonar build followed by an invocation of codesonar analyze) and your default presets directory contains only presets shipped with CodeSonar, specify -no-default-presets either for all stages or none of them.
[-conf-file extra-conf-path] The configuration file at extra-conf-path will be applied to the CodeSonar build/analysis as an additional configuration file.

You can specify -conf-file extra-conf-path multiple times in order to apply multiple additional configuration files. The files will be applied in the order in which they were specified, along with any presets specified with -preset.

Configuration Files: Changing Parameter Settings discusses the issues to consider when you change parameter settings for a given project, including changes in preset files or in the set of presets applied. In particular, if you are performing a build/analysis in multiple stages (that is, one or more invocations of codesonar build followed by an invocation of codesonar analyze) and using -conf-file to apply any of the presets shipped with CodeSonar, specify the same set of presets in the same order for each stage.
[-launchd-group ldgroup] Specifies the parent launch group to use if a new launch daemon is started for this command. The value of ldgroup can be either an integer or a string.
  • string S: specifies the launchd group whose LDGroup Path is S.
  • integer I: specifies the launchd group whose LDGroup ID is I.

When you execute codesonar build or codesonar analyze, CodeSonar sets the Analysis Launch Daemon for the analysis (unless the command is executed with -offline or -foreground). CodeSonar will attempt to start a new launch daemon only if the hub's analysis cloud register does not already contain a suitable launch daemon.
The Analysis Launch Daemon is set as follows, replacing any previous Analysis Launch Daemon setting.

  • If the hub's analysis cloud register contains a matching launch daemon, it is set as the Analysis Launch Daemon and the -launchd-group option has no effect.

    A matching launch daemon is one with identifying tuple (Machine, System User, Hub User, Installation, Key), where Hub User is the hub user who authorized the command, Machine/System User/Installation are those used to run the command, and Key is the key specified with -launchd-key or LAUNCHD_KEY if there is one and ignored otherwise.

  • Otherwise, CodeSonar will attempt to start a new launch daemon and set it as the Analysis Launch Daemon.

    The launch daemon will have identifying tuple (Machine, System User, Hub User, Installation, Key), where Hub User is the hub user who authorized the command, Machine/System User/Installation are those used to run the command, and Key is the key specified with -launchd-key or LAUNCHD_KEY if there is one and the empty string otherwise.

    The Parent LDGroup for the new launch daemon will be set to the launchd group G that is specified by ldgroup. If -launchd-group is not specified, G is the launchd group identified by configuration parameter LAUNCHD_GROUP. If neither is specified, G is the root launchd group.
    G must already exist on the hub, and the authorizing user must have LAUNCHDGROUP_ADD_CHILD permission for G.

Interactions with other options are as follows.

You can change the parent launchd group for an existing launch daemon from the corresponding Launchd Group page.
[-launchd-key ldkey] Specifies the Key to use in determining the Analysis Launch Daemon set by this command.

If -launchd-key is not specified, CodeSonar will use the value of configuration parameter LAUNCHD_KEY. If neither is specified, CodeSonar will ignore the Key field when selecting an existing launch daemon and set the Key field to the empty string when starting a new launch daemon.

Interactions with other options are as follows.
[-srcroot path/to/basedir] When warning information from this analysis is exported in SARIF format, source file paths will be expressed relative to path/to/basedir.
If this option is specified multiple times, the last value will be used.

If one or more values are specified for configuration parameter SRCROOT_PATHS, path/to/basedir will be appended to the list of candidate paths.

The --src-root option to codesonar dump_warnings.py takes precedence over this setting.
[-offline] The codesonar build or codesonar analyze command will be performed offline.
  • Information for later submission to the hub will be accumulated in the build directory/analysis directory.
  • The accumulated offline information must be submitted to the hub by a subsequent codesonar submit-results command.
  • This option takes precedence over the OFFLINE configuration file parameter.
  • If neither -offline nor OFFLINE=Yes is specified, the codesonar build or codesonar analyze command is performed online.
  • If your build/analysis consists of one or more invocations of codesonar build followed by an invocation of codesonar analyze, you can specify a combination of online and offline commands. However, if an online command follows an offline codesonar build command for the same analysis, there must be an intervening codesonar submit-results invocation. If there is not, the online command will exit with an error.
  • If your analysis directory has been used to perform an offline analysis, you must submit the accumulated offline information with codesonar submit-results before using the same directory for further build/analysis commands, whether online or offline.

    To delete the accumulated offline information without submitting it to the hub, specify -clean in the first codesonar build or codesonar analyze invocation of the subsequent analysis.

Conflicting command line options. When a build or analysis step is performed offline, command line options that involve hub interaction are not applicable. The following table lists these options and their corresponding configuration parameters.
For each listed option opt:

  • If opt is specified in a command line that also specifies -offline, the build/analysis will exit with an error.
  • If opt is specified in a command line that does not also specify -offline, the build/analysis will proceed in online mode. If OFFLINE=Yes is specified, CodeSonar will output a warning message.
  • If -offline is specified in a command line that does not also specify opt, the build/analysis will proceed in offline mode. If the configuration parameter corresponding to opt (if any) has a conflicting setting, CodeSonar will output a warning message.
Incompatible option Configuration parameter Notes
-remote REMOTE_ANALYSIS_LAUNCHD An offline build/analysis is always local-managed.
-remote-archive REMOTE_DAEMON_LAUNCHD To specify that an offline analysis should be remote-managed once it has been submitted to the hub and transitions to daemon mode, use the the -remote-archive option with your codesonar submit-results command.
-launchd-group LAUNCHD_GROUP Offline build/analysis does not involve an analysis launch daemon.
-launchd-key LAUNCHD_KEY Offline build/analysis does not involve an analysis launch daemon.
-name ANALYSIS_NAME To assign a name to an offline analysis, specify the -name option with your codesonar submit-results command.
-no-services USE_SERVICES Offline build/analysis does not use a launch daemon, so it will never use Windows services.
-project - To specify the associated project for an offline analysis, use the the -project option with your codesonar submit-results command.
-property - To specify properties for an offline analysis, use the the -property option with your codesonar submit-results command.
-wait - Offline build/analysis always behaves as if -foreground is specified, so is not compatible with -wait.
[-auth authtype],
[-hubuser username],
[-hubpwfile pwfile],
[-hubbearerfile bearerfile],
[-hubcert certfile],
[-hubkey privatekeyfile]		 - Offline build/analysis does not interact with a hub, so it does not make sense to specify hub authentication options.
[protocol://]host:port HUB_ADDRESS Offline build/analysis does not interact with a hub, so it does not make sense to specify a hub location.
- REQUEST_REMOTE_PARSE_SLAVES
REQUEST_REMOTE_ANALYSIS_SLAVES 		Offline build/analysis is always local-requesting.
[-property propkey propval] Adds user-assigned property propkey to the analysis, with value propval.
  • propkey and propval are both strings. Enclose multiple-word strings in quote marks "".
  • Requirements for propkey are as follows.
  • You can specify -property propkey propval multiple times to add multiple user-assigned properties.
  • If you specify -property propkey propval multiple times with the same propkey, the last propval will be used.
  • All hub users will be able to see that propkey is a property key represented on the hub, but only users with ANALYSIS_READ permission for this analysis will be able to see that this analysis has property (propkey, propval).
  • If you specify both -property and -offline, the build/analysis will exit with an error. For more information, see the entry for -offline.
The CodeSonar web GUI also provides functionality for modifying user-assigned analysis properties later.
[-watch-pid pid] [Windows Only] Specify that CodeSonar should watch the process whose PID is pid in addition to the process tree associated with your CodeSonar-facing build command. If the CodeSonar process does not have PROCESS_ALL_ACCESS access against pid, then the process will not be watched.

When you specify this option, specify a command that will not terminate until operations you wish to observe in pid have occurred.

  • If you are performing the CodeSonar build/analysis in an interactive environment, your command can be cmd /c pause or similar.

    For example, if you run the following at a command prompt then you will be prompted to "Press any key to continue", and CodeSonar will observe the process with PID 1234 until you press a key.

    codesonar analyze myProj -watch-pid 1234 [remaining options...] cmd /c pause
  • If you are not performing the build/analysis interactively, your command will generally need to check for conditions that indicate that the required operations have completed.

    For example, suppose you want CodeSonar to observe a series of compilations that ultimately produce an executable file myproj.exe. You could write a batch file projexists.bat that polls for the existence of myproj.exe and exits with success once it is present, and use a command that invokes this batch file: cmd /c projexists.bat.
    Your codesonar analyze command will then be something like the following.

    codesonar analyze myProj -watch-pid 1234 [remaining options...] cmd /c projexists.bat
    (In automated settings you will typically manage the required PID with a variable rather than hard-coding it.)

May be specified multiple times to watch multiple processes.
[-watch-all-pids] [Windows Only] Specify that CodeSonar should watch all processes on the machine for which the CodeSonar process has PROCESS_ALL_ACCESS access. This will include the CodeSonar-facing build command.

When you specify this option, specify a command that will not terminate until all the operations you wish to observe have occurred. See the -watch-pid documentation for some examples.
[-auth authtype],
[-hubuser username],
[-hubpwfile pwfile],
[-hubbearerfile bearerfile],
[-hubcert certfile],
[-hubkey privatekeyfile] 		Specify how CodeSonar should attempt to authenticate the build/analysis command. For details, see Hub Authentication: Authenticated codesonar Subcommands.

If you specify authentication options in a command line that also specifies -offline, the build/analysis will exit with an error.
[[protocol://]host:port] CodeSonar will use the hub at protocol://host:port, failing if one is not already running at that location.
  • If protocol:// is specified, CodeSonar will only try the specified URL. In particular, if http:// is specified then CodeSonar will not try the equivalent https:// URL even if directed to do so by the hub.
  • If protocol:// is not specified, CodeSonar will try http:// first, then redirect to the equivalent https:// URL if directed to do so by the hub.
  • If host:port is not specified, CodeSonar will determine a hub location using the steps described in Hub Location: How CodeSonar Determines Hub Location.

If you specify a hub location in a command line that also specifies -offline, the build/analysis will exit with an error.

The project build and analysis steps can be run separately, as in the following example. The first command instructs CodeSonar to observe the compilation gcc -c myfile.c and update the myproj project accordingly. The second command instructs CodeSonar to analyze myproj and send the results to the default hub.

codesonar build myproj gcc -c myfile.c
codesonar analyze myproj

Hub Project Identification: Examples

The following example command lines illustrate the effects of various -project arguments.

Example 1

Path for analysis files not specified, -project not specified.

codesonar analyze myproj make
Local Files and Directories
Hub Project If the hub already has a project named myproj, the analysis will be associated with it (regardless of its parent project tree). If the hub does not have a project named myproj, CodeSonar will create one as a child of the root project tree.
Analysis Phase Analysis Launch Daemon: local.
Daemon Mode Analysis Launch Daemon: local.

Example 2

Path for analysis files specified, -project not specified.

codesonar analyze c:\csprojects\myproj make
Local Files and Directories
Hub Project If the hub already has a project named myproj, the analysis will be associated with it (regardless of its parent project tree). If the hub does not have a project named myproj, CodeSonar will create one as a child of the root project tree.
Analysis Phase Analysis Launch Daemon: local.
Daemon Mode Analysis Launch Daemon: local.

Example 3

Path for analysis files specified, -project specifies name only.

codesonar analyze c:\csprojects\myproj -project ProjectX make
Local Files and Directories
Hub Project If the hub already has a project named ProjectX, the analysis will be associated with it (regardless of its parent project tree). If the hub does not have a project named ProjectX, CodeSonar will create one as a child of the root project tree.
Analysis Phase Analysis Launch Daemon: local.
Daemon Mode Analysis Launch Daemon: local.

Example 4

Path for analysis files specified, -project specifies name and project tree path.

codesonar analyze c:\csprojects\myproj -project /TeamA/ProjectX make
Local Files and Directories
Hub Project If the hub does not have a project tree named TeamA whose parent project tree is the root project tree, the build/analysis will fail. Otherwise, if the hub has a project named ProjectX, whose parent project tree is TeamA, the analysis will be associated with it. Otherwise, CodeSonar will create a new project named ProjectX as a child of TeamA.
Analysis Phase Analysis Launch Daemon: local.
Daemon Mode Analysis Launch Daemon: local.

Example 5

CodeSonar SaaS build/analysis.

codesonar analyze myproj -remote "/saas/*" make
Local Files and Directories
Hub Project If the hub already has a project named myproj, the analysis will be associated with it (regardless of its parent project tree). If the hub does not have a project named myproj, CodeSonar will create one as a child of the root project tree.
Analysis Phase Analysis Launch Daemon: remote. The SaaS hub will select a suitable launch daemon from its saas launchd group to manage the analysis and analysis data.
Daemon Mode Analysis Launch Daemon: remote. The analysis launch daemon from the analysis phase is also used to service requests from the hub.

Example 6

Invoking the analysis from a continuous integration (CI) tool: local build/analysis, transferring data and control to a launch daemon in the /myremote launchd group when the analysis transitions to daemon mode.

codesonar analyze myproj -remote-archive "/myremote/*" make
Local Files and Directories
Hub Project If the hub already has a project named myproj, the analysis will be associated with it (regardless of its parent project tree). If the hub does not have a project named myproj, CodeSonar will create one as a child of the root project tree.
Analysis Phase Analysis Launch Daemon: local.
Daemon Mode Analysis Launch Daemon: remote. The hub will select a suitable launch daemon from the /myremote/ launchd group to service requests from the hub. This launch daemon will create a new project analysis directory, with contents copied from the analysis directory used in the analysis phase.

If no launch daemons in this group are connected to the hub, daemon mode will also be local-managed. (This can cause problems if the CI tool automatically cleans up the analysis directory.)

Example 7

Local build/analysis, with remotely-managed analysis and separate analysis launch daemons for analysis phase and daemon mode.

codesonar analyze myproj -remote -3 -remote-archive -5 make
Local Files and Directories
Hub Project If the hub already has a project named myproj, the analysis will be associated with it (regardless of its parent project tree). If the hub does not have a project named myproj, CodeSonar will create one as a child of the root project tree.
Analysis Phase Analysis Launch Daemon: remote. The analysis and analysis data will be managed by the launch daemon whose Launch Daemon ID is 3. If no such launch daemon is connected to the hub, the command will fail.
Daemon Mode Analysis Launch Daemon: remote. The launch daemon whose Launch Daemon ID is 5 will service requests from the hub. This launch daemon will create a new project analysis directory, with contents copied from the analysis directory used in the analysis phase.

If no such launch daemon is connected to the hub, daemon mode will be managed by the launch daemon used for the analysis phase.

Language-Specific Examples

Some example CodeSonar command lines for supported languages and combinations of languages.
For tier 3 languages, see the examples in Including Tier 3 Components in a CodeSonar Project and the individual language pages linked from there.

Note: Depending on the hub configuration, you may be prompted for hub user account credentials to authenticate and authorize codesonar build and codesonar analyze commands. See Hub Authentication: Authenticated codesonar Subcommands for more information.

Note that the variety of regular build systems in these examples are intended to illustrate a range of options. You can use any of these build systems, or many others, with any of these languages.

C and C++

Example: a C-only software project built with make.

Example regular build system make
Regular build definition Makefile: 
.PHONY: all clean
all: CComponent

CComponent: A.c
        gcc -o CComponent A.c

clean:
        rm CComponent
Regular build command
make all
Other CodeSonar requirements none
CodeSonar-facing build No extensions to the Makefile are needed.
CodeSonar-facing build command
make all
CodeSonar command line
codesonar analyze cs-myproj make all
CodeSonar recognizes the gcc compiler invocation and updates the cs-myproj project accordingly.

Further example C and C++ build/analysis command lines are provided throughout this manual. Locations include Build and Analysis for C/C++ Projects: command examples and the various tutorials.

See also the multiple language example, below.

Java

Example: a Java-only project built with make.

Example regular build system make
Regular build definition Makefile 
.PHONY: all clean

all: MyJava.class

MyJava.class: MyJava.java
              javac --release 18 MyJava.java

clean:
        rm *.class
Regular build command
make
Other CodeSonar requirements none
CodeSonar-facing build Extend the Makefile as shown. 
.PHONY: all clean

all: MyJava.class

MyJava.class: MyJava.java
          javac --release 18 MyJava.java

csonar_facing: MyJava.java MyJava.class
           cs-java-scan -include-artifacts MyJava.class -include-sources MyJava.java

clean:
        rm *.class
CodeSonar-facing build command
make csonar_facing
This invokes cs-java-scan to identify the Java artifact (MyJava.class) and source (MyJava.java) files. These files are dependencies of the csonar_facing target.
CodeSonar command line
codesonar analyze cs-myproj make csonar_facing
CodeSonar recognizes the cs-java-scan invocation in the CodeSonar-facing build and invokes the Java front end to update the project definition.

For more Java build/analysis examples, see Build and Analysis for Java Projects: Example Command Lines.

See also the multiple language example , below.

C#

Example: a C#-only software project built by invoking a batch file (.bat).

Example regular build system Batch file
Regular build definition csharpbuild.bat 
csc /debug:full /define:DEBUG CsharpModule.cs
Regular build command
cmd /c csharpbuild.bat
Other CodeSonar requirements none
CodeSonar-facing build Extend csharpbuild.bat as shown. 
csc /debug:full /define:DEBUG CsharpModule.cs

if not "%1"=="csonar_facing" goto end
cs-dotnet-scan -include-artifacts CsharpModule.exe -include-sources CsharpModule.cs 
:end
CodeSonar-facing build command
cmd /c csharpbuild.bat csonar_facing
This performs all the steps that were in csharpbuild.bat before it was extended, then invokes cs-dotnet-scan to identify the C# artifact (CsharpModule.exe) and source (CsharpModule.cs) files.
CodeSonar command line
codesonar analyze cs-myproj cmd /c csharpbuild.bat csonar_facing
CodeSonar recognizes the cs-dotnet-scan invocation in the CodeSonar-facing build and invokes the C# front end to update the project definition.

Android Open Source Project (AOSP) (C, C++, Java)

See the example and discussion in codesonar cs_android.py : Prepare and Analyze the Android Open Source Project.

Multiple Languages

Example: a multiple-language project built by invoking a shell script (.sh).
Note that available languages will depend on your license.

Example regular build system Shell script
Regular build definition multibuild.sh 
# /bin/sh

gcc -c A.c
javac --release 18 B.java
Regular build command
sh multibuild.sh

(or ./multibuild.sh)
Other CodeSonar requirements none
CodeSonar-facing build Extend multibuild.sh as shown. 
# /bin/sh

gcc -c A.c
javac --release 18 B.java

if [ $# -gt 0 ]; then
    if [ $1 == "csonar_facing" ]; then
        cs-java-scan -include-artifacts B.class -include-sources B.java
    fi
fi
CodeSonar-facing build command
sh multibuild.sh csonar_facing
This performs all the steps that were in multibuild.sh before it was extended, then invokes cs-java-scan to identify the Java artifacts and source files.
CodeSonar command line
codesonar analyze cs-myproj sh multibuild.sh csonar_facing
CodeSonar recognizes the various commands (gcc, cs-java-scan, ...) in the CodeSonar-facing build and invokes the corresponding language front ends to update the project definition.

The different components have different sets of available warning classes (and classes can be enabled and disabled within those sets).

Go

See the example Makefile and discussion in Including Go Components in a CodeSonar Project

JavaScript and TypeScript

See the example Makefile and discussion in Including JavaScript and TypeScript Components in a CodeSonar Project

Kotlin

Using codesonar kotlin_scan.py (will report warnings from the Kotlin warning classes corresponding to detekt rules) : see the example Makefile and discussion in Including Kotlin Components in a CodeSonar Project

Using cs-java-scan (will report warnings from the Java warning classes): see Build and Analysis for Java Projects: Example Command Lines

Python

See the example Makefile and discussion in Including Python Components in a CodeSonar Project

Rust

See the example Makefile and discussion in Including Rust Components in a CodeSonar Project

Related Links

 

To report problems with this documentation, please visit https://support.codesecure.com/.