#!/usr/bin/env perl
# battalion.wrapper - Launcher for "battalion" main program
# License:  Creative Commons Attribution-NonCommercial-ShareAlike 2.5
# Revision: 080907

# Note:  The license indicated above applies to this file.  It doesn't
# apply to the official Battalion package, or to any file derived from
# that package.

#---------------------------------------------------------------------
#                         license information
#---------------------------------------------------------------------

# This section may not be modified except as approved by the author or
# licensor, or to make non-content changes such as adjustments to par-
# agraph formatting or white space.

# This  version of this software is  distributed  under  the following
# license:
#
#       Creative Commons Attribution-NonCommercial-ShareAlike 2.5

# You may use, modify, and redistribute this software without fees  or
# royalties, but only under the terms and conditions set forth  by the
# license.  In particular, copies and derived works cannot be used for
# commercial purposes.  Additionally, the license propagates to copies
# and derived works. Furthermore, you must provide attribution "in the
# manner  specified  by the  author or licensor".  The latter point is
# discussed below.

# The author [and licensor] hereby specifies that  attribution must be
# handled in the following manner:  a. If the software is interactive,
# any  About or Credits dialog boxes, windows, or output text provided
# by the  original version must be preserved and readily accessible to
# the end user at runtime.  b. If the software is non-interactive,  or
# if it does not  provide  About or Credits dialog boxes, windows,  or
# output text,  the  operating system and/or  desktop environment used
# must provide attribution that is  visible and/or  readily accessible
# to the end user at runtime.

# The following techniques  do not meet the  attribution requirements:
# Attribution through text  files, attribution  through  printed docu-
# mentation,  verbal  attribution, or postings on  external  web sites
# [i.e.,  web  sites  that are not an intrinsic local component of the
# operating system or  desktop environment used].  These  examples are
# provided for illustrative purposes only.

# It should be noted that trademarks are an additional issue.  If this
# software  uses any  trademarks,  trademark-related  restrictions may
# apply.

# This is not a  complete explanation of the  terms and conditions in-
# volved.  For more information, see the Creative Commons Attribution-
# NonCommercial-ShareAlike 2.5 license.

#---------------------------------------------------------------------
#                             explanation
#---------------------------------------------------------------------

# 1. Overview.

# This script performs some setup operations and starts the main  Bat-
# talion [which must be renamed to  "battalion.bin"].  Presently,  the
# following steps are implemented:
#
#     a. It optionally verifies that multiple instances of the program
#        aren't running.  If the test is done,  and multiple instances
#        are running, a fatal-error message is displayed.
#
#     b. It optionally verifies that the program isn't running through
#        VNC. If the test is done, and the program  is running through
#        VNC, a fatal-error message is displayed.
#
#     c. It optionally verifies that  direct rendering  is  available.
#        If the test is done, and direct rendering isn't available,  a
#        fatal-error message is displayed.
#
#     d. If optionally  checks  for  NVidia graphics hardware.  If the
#        test is done,  and NVidia  graphics hardware  is  present,  a
#        warning message is displayed. Note: The user may exit at this
#        point.
#
#     e. It optionally tries to prevent crashes related to system-mem-
#        ory issues.  Specifically,  if memory appears to be low,  the
#        wrapper warns the user and  asks for confirmation before run-
#        ning the main executable.
#
#     f. It optionally  sets  the SDL environment variable  SDL_MOUSE_
#        RELATIVE to a  specified integer [and  exports the variable].
#        This fixes mouse-related problems.
#
#     g. It optionally  adjusts the standard environment variable  LD_
#        LIBRARY_PATH [and exports the variable].  This fixes library-
#        related errors.
#
#     h. It optionally switches to a specified "run" directory.

#---------------------------------------------------------------------

# 2. Requirements.

# At the GUI level,  this program requires  Perl 5,  "glxinfo",  Perl-
# Gtk2, and LACSUB.

# These components are standard, except for LACSUB. You should be able
# to obtain LACSUB from  the  same  place as this file.  Note:  LACSUB
# [like this file] is  distributed under a  Creative Commons  license.
# For more information about  license issues,  see the comments at the
# start of this file.

#---------------------------------------------------------------------
#                        standard module setup
#---------------------------------------------------------------------

require 5.6.1;
use strict;
use Carp;
use warnings;
                                # Trap warnings
$SIG {__WARN__} = sub { die @_; };

#---------------------------------------------------------------------
#                         add CPAN module[s]
#---------------------------------------------------------------------

use Gtk2 '-init';
use Gtk2::SimpleList;

#---------------------------------------------------------------------
#                        add LACSUB module[s]
#---------------------------------------------------------------------

use LACSUB::GUI
 ( @LACSUB::GUI::EXPORT_OK );

#---------------------------------------------------------------------
#                           basic constants
#---------------------------------------------------------------------

use constant ZERO  => 0;        # Zero
use constant ONE   => 1;        # One

use constant FALSE => 0;        # Boolean FALSE
use constant TRUE  => 1;        # Boolean TRUE

#---------------------------------------------------------------------
#                         program parameters
#---------------------------------------------------------------------

my $DIR_BASE        = '__META_PREFIX__';
my $IE              = 'Internal error';
my $PROGNAME        = 'battalion';
my $REVISION        = '080907'; # Revision [or release] string

my $ALERT_ICON_PATH = "$DIR_BASE/misc/alert.png";
my $NEXT_PROGRAM    = "$DIR_BASE/bin/$PROGNAME.bin";

#---------------------------------------------------------------------

# If this program requires direct-rendering support,  set $FLAG_CHECK_
# DIRECT_RENDERING equal to TRUE.  Otherwise,  set this flag  equal to
# FALSE.

my $FLAG_CHECK_DIRECT_RENDERING = TRUE;

#---------------------------------------------------------------------

# If this program has difficulties with NVidia graphics hardware,  set
# $FLAG_CHECK_NVIDIA equal to TRUE.  Otherwise, set this flag equal to
# FALSE.

my $FLAG_CHECK_NVIDIA = TRUE;

#---------------------------------------------------------------------

# If you'd like  to prohibit  multiple instances,  set $FLAG_PROHIBIT_
# MULTI_INSTANCE to TRUE. Otherwise, set this flag to FALSE.

my $FLAG_PROHIBIT_MULTI_INSTANCE = TRUE;

#---------------------------------------------------------------------

# If this program shouldn't try to run under VNC,  set $FLAG_PROHIBIT_
# VNC equal to TRUE. Otherwise, set this flag equal to FALSE.

my $FLAG_PROHIBIT_VNC = TRUE;

#---------------------------------------------------------------------

# If  you'd  like to enforce  a minimum-memory requirement,  set $MIN_
# FREE_KB to a memory-size value (in KB).  Otherwise, set this parame-
# ter to zero.

# If $MIN_FREE_KB specifies a positive integer,  this program tries to
# estimate the amount of system memory that's available (or that could
# be made available).  If the estimated amount is less than the speci-
# fied amount,  it'll warn the user and prompt for confirmation before
# proceeding.

my $MIN_FREE_KB = 15000;

#---------------------------------------------------------------------

# If $SDL_MOUSE_RELATIVE is defined, and it specifies zero  or a posi-
# tive integer, the wrapper sets the environment  variable  SDL_MOUSE_
# RELATIVE  equal  to the  specified number  [and  exports  the  vari-
# able].  Otherwise, the wrapper doesn't look at or change  SDL_MOUSE_
# RELATIVE.

# This parameter is used to prevent mouse-related problems:
#
#     a. If the  main executable uses SDL,  and  the mouse is  slow or
#        "laggy", try setting $SDL_MOUSE_RELATIVE to ZERO.
#
#     b. If you're experiencing other mouse-related problems, try set-
#        ting this parameter to ONE.
#
#     c. If these settings cause problems,  as opposed to fixing them,
#        set $SDL_MOUSE_RELATIVE to -1 or undefine it.

my $SDL_MOUSE_RELATIVE = -1;

#---------------------------------------------------------------------

# If the main executable requires any special LD_LIBRARY_PATH entries,
# you can specify them here.  Set $EXTRA_LIBPATHS to a colon-delimited
# list of absolute directory paths.  If there's only one entry, no co-
# lons are required.

# If  no special  LD_LIBRARY_PATH entries  are  required,  set $EXTRA_
# LIBPATHS to an empty string.

my $EXTRA_LIBPATHS = "";

#---------------------------------------------------------------------

# If you'd like to run the main executable from a  specific directory,
# set $PATH_RUNDIR equal to an absolute path for the directory. Other-
# wise, set this parameter equal to an empty string.

my $PATH_RUNDIR = "";

#---------------------------------------------------------------------
#                            main routine
#---------------------------------------------------------------------

sub Main
{
    my $str;                    # Scratch

#---------------------------------------------------------------------
# Verify that program isn't already running.

    &VerifyNotRunning
    (
        -icon_path    => $ALERT_ICON_PATH ,
        -name         => $PROGNAME        ,

        -pattern_this =>
            ':\d\d\s(perl |)(\S+/|)' . $PROGNAME . '(|\.wrapper)\s' ,
        -pattern_next =>
            ':\d\d\s(perl |)(\S+/|)' . $PROGNAME . '\.bin\s'
    )
        if $FLAG_PROHIBIT_MULTI_INSTANCE;

#---------------------------------------------------------------------
# Go to user's home directory.

    my $HOME = $ENV {HOME};
    $HOME = '/' unless defined $HOME;
    chdir $HOME;

#---------------------------------------------------------------------
# Handle VNC test (if enabled).

    &AbortIfVNC
    (
        -icon_path => $ALERT_ICON_PATH ,
        -name      => $PROGNAME
    )
        if $FLAG_PROHIBIT_VNC;

#---------------------------------------------------------------------
# Handle direct-rendering test (if enabled).

    &AbortUnlessDRI
    (
        -icon_path => $ALERT_ICON_PATH ,
        -name      => $PROGNAME
    )
        if $FLAG_CHECK_DIRECT_RENDERING;

#---------------------------------------------------------------------
# NVidia-related kludge.

    &CheckNVidia
    (
        -icon_path => $ALERT_ICON_PATH ,
        -name      => $PROGNAME
    )
        if $FLAG_CHECK_NVIDIA;

#---------------------------------------------------------------------
# Handle available-memory test (if enabled).

    &CheckAvailableMemory
    (
        -icon_path => $ALERT_ICON_PATH ,
        -min_free  => $MIN_FREE_KB     ,
        -name      => $PROGNAME
    )
        if defined ($MIN_FREE_KB) && ($MIN_FREE_KB =~ m@^[1-9]\d*\z@);

#---------------------------------------------------------------------
# Set SDL_MOUSE_RELATIVE, if necessary.

    if (defined ($SDL_MOUSE_RELATIVE) &&
        ($SDL_MOUSE_RELATIVE =~ m@^\d+\z@))
    {
        $ENV {SDL_MOUSE_RELATIVE} = $SDL_MOUSE_RELATIVE;
    }

#---------------------------------------------------------------------
# Adjust LD_LIBRARY_PATH, if necessary.

    if (defined ($EXTRA_LIBPATHS) && length ($EXTRA_LIBPATHS))
    {
        $str =  $ENV {LD_LIBRARY_PATH};
        $str =  "" unless defined $str;
        $str =  "$EXTRA_LIBPATHS:$str";
        $str =~ s@^:+@@;
        $str =~ s@:+\z@@;
        $str =~ y/:/:/s;
        $ENV {LD_LIBRARY_PATH} = $str;
    }

#---------------------------------------------------------------------
# Go to appropriate directory.

                                # Use a specified directory?
    if (!defined ($PATH_RUNDIR) || !length ($PATH_RUNDIR) ||
        (!-d $PATH_RUNDIR) || !chdir ($PATH_RUNDIR))
    {                           # No  - Use home directory instead
        my $HOME = $ENV {HOME};
        $HOME = '/' unless defined $HOME;
        chdir $HOME;
    }

#---------------------------------------------------------------------
# Wrap it up.

    exec $NEXT_PROGRAM, @ARGV;  # Chain to target program
}

#---------------------------------------------------------------------
#                            main program
#---------------------------------------------------------------------

&Main();                        # Call the main routine
exit ZERO;                      # Normal exit