Makes fork() in debugger to open a new Tmux window
This documentation refers to the module contained in the distribution
Debug-Fork-Tmux version 1.000007.
#!/usr/bin/perl -d
#
# ABSTRACT: Debug the fork()-contained code in this file
#
# Make fork()s debuggable with Tmux
use Debug::Fork::Tmux;
# See what happens in your debugger then...
fork;
The real usage example of this module is:
perl -MDebug::Fork::Tmux -d your_script.pl
The Perl's standard debugger requires additional stuff when the debugged Perl program use the fork() built-in.
This module is about to solve the trouble which visible like this:
######### Forked, but do not know how to create a new TTY. ######### Since two debuggers fight for the same TTY, input is severely entangled. I know how to switch the output to a different window in xterms, OS/2 consoles, and Mac OS X Terminal.app only. For a manual switch, put the name of the created TTY in $DB::fork_TTY, or define a function DB::get_fork_TTY() returning this. On UNIX-like systems one can get the name of a TTY for the given window by typing tty, and disconnect the shell from TTY by sleep 1000000.
OS/2 is a fun for me but in the past. Mac OS
X is a more chance but still isn't real. And for
xterm ... who wants to keep it on your server? Gimme
some stones to throw on that one.
But the pseudo-terminal device isn't much about GUIs by
its nature so the problem behind the bars of the perl5db.pl report ( see more detailed problem
description at the PerlMonks thread ) is the consoles management.
It's a kind of a tricky, for example, to start the next
ssh session initiated from the machine serving as an
sshd server for the existing session.
Thus we kind of have to give a chance to the consoles management with
a software capable to run on a server machine without as much
dependencies as an xterm. This module is a try to pick
the Tmux windows
manager for such a task.
All of the following are functions:
DB::get_fork_TTY()
Finds new TTY for the fork()ed process.
Takes no arguments. Returns Str name of the
tty device of the <tmux>'s new window created for
the debugger's new process.
Sets the $DB::fork_TTY to the same Str
value.
_spawn_tty()
Creates a TTY device and returns Str its
name.
_tmux_new_window()
Creates a given tmux window and returns Str
its id/number.
_tmux_window_tty(
$window_id )
Finds a given tmux window's tty name and returns its
Str name based on a given window id/number typically
from "_tmux_new_window()".
_read_from_cmd( $cmd
=> @args )
Takes the list containing the Str system() command and Array its
arguments and executes it. Reads Str the output and
returns it. Throws if no output or if the command failed.
_croak_on_cmd(
$cmd => @args, $happen )
Takes the Str command, Array its arguments
and Str the reason of its failure, examines the
$? and dies with explanation on the system() command failure.
The module requires the Tmux window manager for the console to be present in the system.
Configuration is made via environment variables, the default is taken for each of them with no such variable is set in the environment:
SPUNGE_TMUX_FQDN
The tmux binary name with the full path.
Default : /usr/local/bin/tmux
SPUNGE_TMUX_CMD_NEWW
The system() arguments for a tmux command
for opening a new window and with output of a window address from
tmux. String is sliced by spaces to be a list of
parameters.
Default : neww -P
SPUNGE_TMUX_CMD_NEWW_EXEC
The system() or a shell command to be given to the
SPUNGE_TMUX_CMD_NEWW command to be executed in a brand
new created window. It should wait unexpectedly and do nothing till
the debugger catches the device and puts in into the proper use.
Default : sleep 1000000
SPUNGE_TMUX_CMD_TTY
Command- line parameter(s) for a tmux command to find a
tty name in the output. The string is sliced then by
spaces. The tmux's window address is added then as the
very last argument.
Default : lsp -F #{pane_tty} -t
Typically the error message starts with the command the Debug::Fork::Tmux tried to execute, including the command's arguments.
The command was not taken by the system as an executable binary file.
Command did not output exactly one line of the text.
Command outputs more than one line of the text.
Command outputs exactly one line of the text and the line is empty.
There was failure executing the command
Command was killed by the signal X and the coredump is (not) located in Y.
Command was not failed but there are reasons to throw an error like the wrong command's output.
* Perl 5.6.0+ is available from The Perl website
* Config, Cwd, DB,
ExtUtils::MakeMaker, File::Find, File::Spec are available in core Perl
distribution version 5.6.0 and later
* Const::Fast is available from CPAN
* Module::Build is available in core Perl
distribution since version 5.9.4
* Scalar::Util is available in core Perl
distribution since version 5.7.3
* Sort::Versions is available from CPAN
* Test::Exception is available from CPAN
* Test::More is available in core Perl
distribution since version 5.6.2
* Test::Most is available from CPAN
* Test::Strict is available from CPAN
* autodie is available in core Perl
distribution since version 5.10.1
* Tmux v1.6+ is available from The Tmux website
Most of them can easily be found in your operating system distribution/repository.
You can make new bug reports, and view existing ones, through the web interface at http://bugs.vereshagin.org/product/Debug-Fork-Tmux.
The web site of Debug::Fork::Tmux currently consists of only one page cause it's a very small module.
You may want to visit a GitHub page, too.
You can find documentation for this module with the perldoc command.
perldoc Debug::Fork::Tmux
The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.
A modern, open-source CPAN search engine, useful to view POD in HTML format.
The default CPAN search engine, useful to view POD in HTML format.
The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.
The AnnoCPAN is a website that allows community annotations of Perl module documentation.
The CPAN Ratings is a website that allows community ratings and reviews of Perl modules.
The CPAN Forum is a web forum for discussing Perl modules.
The CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution.
The CPAN Testers is a network of smokers who run automated tests on uploaded CPAN distributions.
The CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms.
The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution.
You can email the author of this module at
peter@vereshagin.org asking for help with any problems
you have.
Please report any bugs or feature requests by email to
peter@vereshagin.org, or through the web interface at
http://bugs.vereshagin.org/product/Debug-Fork-Tmux.
You will be automatically notified of any progress on the request by
the system.
The code is open to the world, and available for you to hack on. Please feel free to browse it and play with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull from your repository :)
http://gitweb.vereshagin.org/Debug-Fork-Tmux
git clone https://github.com/petr999/Debug-Fork-Tmux.git
Peter Vereshagin <peter@vereshagin.org>
This software is Copyright (c) 2012 by Peter Vereshagin.
This is free software, licensed under:
The (three-clause) BSD License
Please see those modules/websites for more information related to this module.
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.