2.1 Profiling build execution timing and dependencies

  $ remake --profile[=callgrind|json] # target...

The --profile option enables dependency and timing output from build execution. The data can be used to determine where your build system spends it’s time. By default, the --profile option outputs profiling data in the callgrind format ⁴ which can be used with kcachegrind⁵ or other tools⁶ that work with this format. Each recursive call to GNU Remake generates its own output in the starting directory named callgrind.out.<pid> where pid is the PID of the GNU Remake process.

By default, profiling data is written in the same directory where GNU Remake is executed. This includes recursive calls. The --profile-directory argument can be used to specify a single directory for all profiling data. This is taken to be relative to the initial invocation of GNU Remake unless the path begins with ~ or /.

2.1.1 JSON-formatted profiling data

The --profile option also accepts a json flag that will output profiling data in json-formatted files. With the following formatting:

 {
     "version":"1.0.0",
     "pid":1234,
     "parent":{
         "pid":1230,
         "target":"target-name"
     },
     "jobs": 8,
     "server": true,
     "creator":"remake"
     "argv":[
         "arg0",
         "arg1",
         "arg2"
     ],
     "directory":"path/to/working/dir",
     "status":"Normal program termination",
     "start":1235.6789,
     "end":1240.0123,
     "resolution":1000,
     "entry":[
         "all",
         "other"
     ],
     "targets":[
         {
             "name":"all",
             "file":"path/to/file/with/target",
             "line":100,
             "start":123.123,
             "deps":null,
             "recipe":124.0,
             "end":124.124,
             "depends":[
                 "dependent",
                 "target0",
                 "target1",
                 "target2"
             ]
         }
     ]
 }

2.1.1.1 Top-level field definitions

version

The version field specifies the version of build.json file.

pid

The PID of the GNU Remake execution that created this file

parent.pid

If present, this PID of the GNU Remake process that recursively called the current GNU Remake process

parent.target

If present, the name of the target the parent GNU Remake process that recusively called the current GNU Remake process.

jobs

If present, either unlimited when parallel jobs were not restricted. Or an integer value reprenting the maximum number of available jobs.

server

True if connected to a jobserver

creator

A string representing the version of GNU Remake that generated this file

argv

An array of strings that represent the command used to start GNU Remake

directory

Path to the starting directory, generally the path current directory or the value passed to GNU Remake with -C path/to/subdir

status

String representing what caused GNU Remake to exit

start

Timestamp in seconds representing when GNU Remake started

end

Timestamp in seconds representing when GNU Remake ended

resolution

Number of nanoseconds specifying the minimum resolution of timestamps in the output

entry

An array of targets that were requested to be built.

targets

An array of target specifications

2.1.1.2 Target field definitions

name

Name of the target

file

Path to the file that contains the target definition relative to the top-level directory field

line

Line number of the name target in the file field

start

Timestamp when the target was first considered by GNU Remake

deps

Timestamp when GNU Remake marked the target as waiting on dependencies. Or null if it was not marked as waiting.

recipe

Timestamp when the recipe for the target began execution. Or null if the recipe did not need to execute.

end

Timestamp when the target was considered complete

depends

Array of target names that this target depended on.