Using breakpoints

You can add ecbreakpoint to makefile rule bodies as in Figure 1. eMake pauses the job when it encounters the breakpoint. The Cluster Manager then displays the breakpoint panel on the Build Details page (Figure 3). Click a breakpoint action to display the Break Point Detail page.

Figure 1: Makefile using the ecbreakpoint program

Figure 2 illustrates a build (chronic_641) with jobs paused by ecbreakpoint.

Figure 2: Paused job

Figure 3: Breakpoint UI on the Build Details page

If you have sufficient permissions , you can interact with the ecbreakpoint program within the web interface. There are currently four actions available for ecbreakpoint :

Click Retry or Continue to delete the current ecbreakpoint.

Click Agent Command or Shell Command to go to the Break Point Details page (illustrated in Figure 4), which provides more information and interaction with the breakpoint. After you issue a command, the response is shown as Waiting for response…​. Refresh the page after a few seconds to view the result (the lower portion of Figure 4). The value of the request Type column can be S or A, which is shell or agent command respectively.

Figure 4 illustrates that pstree -alp was passed to the agent. The pstree command shows a hierarchical representation of the process tree and is often useful to see what commands agents are running. Note that pstree is a child of ecbreakpoint and ecbreakpoint is a child of agent 0. The compilation and linking processes will probably be finished by the time you run pstree. You may see other processes, for example, processes launched in the background such as license managers, that may provide clues about what is happening.

Figure 4: ` pstree` command run from the breakpoint menu

You can also get session state information to send to Electric Cloud technical support. For contact information, see https://support.cloudbees.com/hc/en-us/categories/360002059512 .

Figure 5: Session state information

You can access ecbreakpoint from the command line or scripts using the curl command. CloudBees Build Acceleration ships with curl in the ecloud bin directory. Figure 3 shows the IP address and port for ecbreakpoint. Use those values in curl and make sure to use the appropriate escape characters for spaces, slashes, and so on.

Following is an example for running the ps command on the agent:

Table 2 contains URLs you can use to access ecbreakpoint.

Table 2: ecbreakpoint access URLs

The makefile in Figure 1 contained one ecbreakpoint command. If you want to set multiple breakpoints in your build, you must use the ecbreakpoint --label command line option to distinguish them in the UI. Notice the --label option in the Makefile in Figure 6.

Figure 6: Makefile with a label for each target

When the Makefile in Figure 6 runs, the Cluster Manager displays labels for each breakpoint (Figure 7).

Figure 7: Labeled breakpoints on the Build Details page

The label command may need more information than just the target name. For example, if a pattern rule was called multiple times from various submakes where the C files had the same names, this could result in a situation similar to the one in Figure 8 where the labels are the same.

Figure 8: Breakpoint labels with the same name

You can make labels more distinct by specifying the label as --label="$(@) \_pwd", which results in the output in Figure 10.

Figure 9: ` ecbreakpoint` label option augmented with the working directory

Figure 10: Breakpoint labels with the working directory

You can also specify the breakpoint by passing in a file. Begin the command argument with file: <yourpath> and the file will be read from the path specified for the runAgentCmd request.

Example breakpoint contained in a file named test.txt :

Example of passing in the breakpoint contained in test.txt :

If the breakpoint does not trigger when you think it should, look in the agent log files. If there are Tcl errors with your breakpoint, you may see something like the following:

Be sure that the text you are looking for actually appears in the stdout. If the text is in the output, open the tkcon console (in the ecloud bin directory) and test your regex code. Modify the regex until it works.

Output from agent-side breakpoint 'puts' statements is written to agent logs and not the build’s stdout. If the agent breakpoint stops the build with ecbreakpoint, you can use the Break Points panel to determine which agent log to examine. However, if your breakpoint calls a tool such as strace, you may have to examine all agent logs. On Linux, one useful hint to remember is that Gnu ` tail(1)` can tail multiple files at the same time ( tail -f /var/log/ecagent?.log ).

When creating agent breakpoints, it is useful to have an open editor window with the cmtool runAgentCommand set breakpoint command that you are modifying. When working with the breakpoint, you can execute it from within the editor by selecting the code in Vim’s visual mode and then using the 'ex' command line to feed it into the shell for execution. You do not need to clear the breakpoint before setting a new one because setting a breakpoint overwrites the current one. You can also cut-and-paste the breakpoint code into a command window.

In the .vimrc, configure the makeprg variable to call eMake instead of GNU Make; type ` :make` from the ex command line to invoke the makefile.

In emacs, you can feed text to the shell using 'M-|'. Select the region of the buffer you want to send to the shell, and then type M-|.