/ 
Image-DS9-v1.0.0
River stage zero No dependents
/ Image::DS9::Manual::Install

NAME

Image::DS9::Manual::Install - Installation and testing of Image::DS9

VERSION

version v1.0.0

DESCRIPTION

Dependencies

These dependencies are special (the others are all CPAN modules which should install easily).

Alien::XPA, IPC::XPA

These are on CPAN, and should automatically be installed by your CPAN client. This should be straightforward on *nix platforms. The distributions test well on CPAN Testers.

Experience on Windows is sparse, and not well tested by CPAN testers.

ds9

ds9 is available for Linux, MacOS, and Windows. Please install this prior to installation of Image::DS9.

Testing

Because ds9 runs in a separate process from the Perl tests, coordination is required between the two to ensure that an instance of ds9 is available when the tests expect it to be.

Note: A graphical environment is required.

ds9 is a graphical program; if it is started outside of such an environment, it will exit, and the tests will fail.

An initial test, t/000-graphical_environment.t attempts to run ds9; if ds9 exits with error, the entire test suite will be skipped.

Starting an instance of ds9

By default each test file will automatically attempt to start an instance of ds9, run tests with it, and then shut it down. The repeated starting and stopping of ds9 is tiresome, and is very slow.

There are alternatives:

Semi-Manual start

Set (and export) the environment variables

export TEST_IMAGE_DS9_TERMINATE_ON_DESTROY=no

before running the CPAN client (e.g. cpan, cpanm). The first test will start ds9 and detach it from the test framework and keep it running for the rest of the tests.

You will need to manually shut down the instance of ds9 after the tests are complete.

Manual Start

First, ensure that all of the test dependencies are installed. This can be accomplished with cpanm after extracting the distribution file.

cpanm --installdeps .

Start ds9 prior to running the tests via

export TEST_IMAGE_DS9_TERMINATE_ON_DESTROY=no
perl -Ilib t/lib/TestServer.pm

Don't try running ds9 directly; the tests require it be available running in a particular environment.

You will need to shut ds9 down after the tests are complete.

xvfb-run

If the xvfb-run command is available on your platform, it can be used to run the tests in a X server running in a virtual frame buffer. Set the following environment variables

export TEST_IMAGE_DS9_TERMINATE_ON_DESTROY=no
export TEST_IMAGE_DS9_XVFB=yes

before running your CPAN client. You will need to manually shut ds9 down (the virtual X server will shut down as well)

XPA_METHOD=local perl-MImage::DS9 \
   -e 'Image::DS9->new( {Server => q{ImageDS9} })->quit'

Parallel tests

Don't. The tests don't start up independent copies of ds9, and simultaneously running tests will leave ds9 in a different state than tests expect.

It is possible to rewrite the tests to each use independent instances, but it's not really worth it.

SUPPORT

Bugs

Please report any bugs or feature requests to bug-image-ds9@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=Image-DS9

Source

Source is available at

https://gitlab.com/djerius/image-ds9

and may be cloned from

https://gitlab.com/djerius/image-ds9.git

SEE ALSO

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

AUTHOR

Diab Jerius <djerius@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2017 by Smithsonian Astrophysical Observatory.

This is free software, licensed under:

The GNU General Public License, Version 3, June 2007