NAME
   Debug::Fork::Tmux - Makes fork() in debugger to open a new Tmux window

VERSION
   This documentation refers to the module contained in the distribution
   "Debug-Fork-Tmux" version 1.000012.

SYNOPSIS
       #!/usr/bin/perl -d
       #
       # ABSTRACT: Debug the fork()-contained code in this file
       #
       ## Works only under Tmux: http://tmux.sf.net
       #
       # Make fork()s debuggable with Tmux
       use Debug::Fork::Tmux;

       # See what happens in your debugger then...
       fork;

DESCRIPTION
   Make sure you have the running "Tmux" window manager:

       $ tmux

   *   Only "Tmux" version 1.6 and higher works with "Debug::Fork::Tmux".
       See "DEPENDENCIES".

   *   It is not necessary to run this under "Tmux", see "Attaching to the
       other "Tmux" session".

   Then the real usage example of this module is:

       $ perl -MDebug::Fork::Tmux -d your_script.pl

   As Perl's standard debugger requires additional code to be written and
   used when the debugged Perl program use the fork() built-in.

   This module is about to solve the trouble which is used to be observed
   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.

   All of that is about getting the pseudo-terminal device for another part
   of user interface. This is probably why only the "GUI"s are mentioned
   here: "OS/2" 'Command Prompt', "Mac OS X"'s "Terminal.app" and an
   "xterm". For those of you who develop server-side stuff it should be
   known that keeping "GUI" on the server is far from always to be
   available as an option no matter if it's a production or a development
   environment.

   The most ridiculous for every "TUI" (the "ssh" particularly) user is
   that the pseudo-terminal device isn't that much about "GUI"s by its
   nature so the problem behind the bars of the perl5db.pl report (see more
   detailed problem description at the PerlMonks thread
   <http://perlmonks.org/?node_id=128283>) 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
   <http://tmux.sf.net> windows manager for such a task.

   Because of highly-developed scripting capabilities of "Tmux" any user
   can supply the 'window' or a 'pane' to Perl's debugger making it
   suitable to debug the separate process in a different "UI" instance.
   Also this adds the features like "groupware": imagine that your mate can
   debug the process you've just "fork()ed" by mean of attaching the same
   "tmux" you are running on a server. While you keep working on a process
   that called a "fork()".

SUBROUTINES/METHODS
   All of the following are functions:

 PUBLIC
  "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.

 PRIVATE
  "_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.

CONFIGURATION AND ENVIRONMENT
   The module requires the Tmux <http://tmux.sf.net> window manager for the
   console to be present in the system.

   This means that it requires the "Unix"-like operating system not only to
   have a fork implemented and a "TTY" device name supplement but the
   system should have Tmux up and running.

   Therefore "Cygwin" for example isn't in at this moment, see the
   explanation
   <http://permalink.gmane.org/gmane.comp.terminal-emulators.tmux.user/1354
   > why.

   Configuration is made via environment variables, the default is taken
   for each of them with no such variable is set in the environment:

 "DFTMUX_FQFN"
   The "tmux" binary name with the full path.

   Default : The first of those for executable to exist:

   "PATH" environment variable contents
   Path to the Perl binary interpreter
   Current directory

   and just the "tmux" as a fallback if none of above is the location of
   the "tmux" executable file.

 "DFTMUX_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"

 "DFTMUX_CMD_NEWW_EXEC"
   The system() or a shell command to be given to the "DFTMUX_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"

 "DFTMUX_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"

 Earlier versions' "SPUNGE_*" environment variables
   Till v1.000009 the module was controlled by the environment variables
   like "SPUNGE_TMUX_FQDN". Those are deprecated and should be replaced in
   your configuration(s) onto the "DFTMUX_"-prefixed ones.

 Attaching to the other "Tmux" session
   For the case you can not or don't want to use the current "tmux" session
   you are running in, you may want to have the separate "tmux" server up
   and running and use its windows or panes to be created. This can be done
   by mean of prepending the correct "-L" or "-S" switch to the start of
   the every of the command-line parameters string to be used, for example:

       $ DFTMUX_CMD_NEWW="-L default neww -P" \
       > DFTMUX_CMD_TTY="-L default lsp -F #{pane_tty} -t" \
       > perl -MDebug::Fork::Tmux -d your_script.pl

DIAGNOSTICS
   *   "The command ..."

       Typically the error message starts with the command the
       Debug::Fork::Tmux tried to execute, including the command's
       arguments.

   *   "failed opening command: ..."

       The command was not taken by the system as an executable binary
       file.

   *   "... didn't write a line"

   *   "failed reading command: ..."

       Command did not output exactly one line of the text.

   *   "... did not finish"

       Command outputs more than one line of the text.

   *   "provided empty string"

       Command outputs exactly one line of the text and the line is empty.

   *   "failed to execute: ..."

       There was failure executing the command

   *   "child died with(out) signal X, Y coredump"

       Command was killed by the signal X and the coredump is (not) located
       in Y.

   *   "child exited with value X"

       Command was not failed but there are reasons to throw an error like
       the wrong command's output.

DEPENDENCIES
   * "Perl 5.8.9+" is available from The Perl website <http://www.perl.org>

   * Config, Cwd, DB, ExtUtils::MakeMaker, File::Find, File::Spec,
   File::Basename, Scalar::Util, Test::More are available in core "Perl"
   distribution version 5.8.9 and later

   * Const::Fast is available from "CPAN"

   * Module::Build is available in core "Perl" distribution since version
   5.9.4

   * Sort::Versions is available from "CPAN"

   * Test::Exception is available from "CPAN"

   * Test::Most is available from "CPAN"

   * Test::Strict is available from "CPAN"

   * Env::Path 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
   <http://tmux.sourceforge.net>

   Most of them can easily be found in your operating system
   distribution/repository.

BUGS AND LIMITATIONS
   You can make new bug reports, and view existing ones, through the web
   interface at <http://bugs.vereshagin.org/product/Debug-Fork-Tmux>.

WEB SITE
   The web site of Debug::Fork::Tmux
   <http://gitweb.vereshagin.org/Debug-Fork-Tmux/README.html> currently
   consists of only one page cause it's a very small module.

   You may want to visit a GitHub page
   <https://github.com/petr999/Debug-Fork-Tmux>, too.

SUPPORT
 Perldoc
   You can find documentation for this module with the perldoc command.

     perldoc Debug::Fork::Tmux

 Websites
   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.

   *   MetaCPAN

       A modern, open-source CPAN search engine, useful to view POD in HTML
       format.

       <http://metacpan.org/release/Debug-Fork-Tmux>

   *   Search CPAN

       The default CPAN search engine, useful to view POD in HTML format.

       <http://search.cpan.org/dist/Debug-Fork-Tmux>

   *   RT: CPAN's Bug Tracker

       The RT ( Request Tracker ) website is the default bug/issue tracking
       system for CPAN.

       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Debug-Fork-Tmux>

   *   AnnoCPAN

       The AnnoCPAN is a website that allows community annotations of Perl
       module documentation.

       <http://annocpan.org/dist/Debug-Fork-Tmux>

   *   CPAN Ratings

       The CPAN Ratings is a website that allows community ratings and
       reviews of Perl modules.

       <http://cpanratings.perl.org/d/Debug-Fork-Tmux>

   *   CPAN Forum

       The CPAN Forum is a web forum for discussing Perl modules.

       <http://cpanforum.com/dist/Debug-Fork-Tmux>

   *   CPANTS

       The CPANTS is a website that analyzes the Kwalitee ( code metrics )
       of a distribution.

       <http://cpants.perl.org/dist/overview/Debug-Fork-Tmux>

   *   CPAN Testers

       The CPAN Testers is a network of smokers who run automated tests on
       uploaded CPAN distributions.

       <http://www.cpantesters.org/distro/D/Debug-Fork-Tmux>

   *   CPAN Testers Matrix

       The CPAN Testers Matrix is a website that provides a visual overview
       of the test results for a distribution on various Perls/platforms.

       <http://matrix.cpantesters.org/?dist=Debug-Fork-Tmux>

   *   CPAN Testers Dependencies

       The CPAN Testers Dependencies is a website that shows a chart of the
       test results of all dependencies for a distribution.

       <http://deps.cpantesters.org/?module=Debug::Fork::Tmux>

 Email
   You can email the author of this module at "[email protected]" asking
   for help with any problems you have.

 Bugs / Feature Requests
   Please report any bugs or feature requests by email to
   "[email protected]", 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.

 Source Code
   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

AUTHOR
   Peter Vereshagin <http://vereshagin.org> <[email protected]>

COPYRIGHT AND LICENSE
   This software is Copyright (c) 2013 by Peter Vereshagin.

   This is free software, licensed under:

     The (three-clause) BSD License

SEE ALSO
   Please see those modules/websites for more information related to this
   module.

   *   Debug::Fork::Tmux::Config

   *   <http://perlmonks.org/?node_id=128283>

   *   <nntp://nntp.perl.org/perl.debugger>

   *   <http://debugger.perl.org/>

DISCLAIMER OF WARRANTY
   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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.