Tk::Zinc - a canvas widget with groups, transformations and OpenGL rendering

This README describes building and using the exported Perl distribution.
For instructions on generating it from the full TkZinc repository, see the
repository's top-level README.md.

Requirements:

* Perl 5.8.0 or later.
* Perl/Tk 804, including the headers needed to build extensions.
* ExtUtils::MakeMaker 6.98 or later for building.
* Test::More 0.98 or later for running the tests.
* A C compiler with stdint.h, a compatible make utility, and the system
  OpenGL and GLU development libraries. Linux also requires X11 development
  libraries.

Older Perl installations may need updates to the build and test modules.
Choose module versions compatible with your Perl; the newest module releases
may have higher Perl requirements. Perl 5.8.0 is the minimum compatibility
target, not a recommendation to install an obsolete Perl release.

The current build has been tested with Perl 5.30, Perl/Tk 804.033 on
Ubuntu/WSL, and Perl/Tk 804.036 with 64-bit Strawberry Perl on Windows.
Perl 5.8.0 itself has not yet been tested with the current sources.

The distribution bundles GLEW 2.3.1 as source. It is compiled into the
extension with private symbols; no separate GLEW installation or glew32.dll
is needed. See third_party/glew/README.tkzinc.md and
third_party/glew/LICENSE.txt.

Linux and WSL (Ubuntu):

Install the build dependencies:

  sudo apt update
  sudo apt install build-essential perl perl-tk \
      libx11-dev libxext-dev libgl-dev libglu1-mesa-dev

From the exported distribution directory:

  perl Makefile.PL
  make
  make test

To run the demos before installing:

  perl -Mblib demos/zinc-demos

To install into your chosen Perl installation (permissions may be required):

  make install

GUI tests need an X display. For automated tests without a visible window:

  sudo apt install xvfb xauth
  xvfb-run -a make test

Windows:

Use Perl with Perl/Tk and a C compiler and make utility compatible with that
Perl installation. The build has been tested with 64-bit Strawberry Perl,
which includes GCC and gmake. Other Perl distributions need a matching
toolchain and have not been verified here.

From the exported distribution directory, using Strawberry Perl:

  perl Makefile.PL
  gmake
  gmake test

To run the demos before installing:

  perl -Mblib demos/zinc-demos

To install:

  gmake install

macOS:

The project contains historical macOS support, but the current Perl build
has not been verified on macOS. The old Fink installation instructions are
obsolete. A matching Perl/Tk development environment, C compiler, make,
and the graphics dependencies are required.

Build options:

  perl Makefile.PL --with-gl=yes --with-atc=yes --with-shape=yes

These are the defaults. Use "no" to disable an option. Shape support is
always disabled on Windows. Disabling OpenGL rendering does not remove
all OpenGL/GLU build dependencies.

The animated gradient test keeps all transformations but redraws fewer
frames by default. Set TKZINC_TEST_FULL_ANIMATION=1 for the full visual
animation.

Using another Perl/Tk installation:

Run Makefile.PL, the build, tests, and your application with the same Perl
and Perl/Tk installation. If using PERL5LIB, include that installation's
library and architecture-specific directories throughout these steps.
Do not mix compiled extensions from different Perl installations.

Exporting from the full source repository:

The separate Perl/export2cpan.pl script requires File::Path 2.06 or later
for make_path. This is not a runtime dependency of Tk::Zinc. In particular,
Perl 5.8.0 and 5.8.8 need a File::Path update before running the exporter.
See the top-level README.md for the export workflow.

Documentation and support:

Documentation and the full source package are available at:
https://github.com/asb-capfan/TkZinc

After installation, zinc-demos provides a front-end to more than 30 demos.

Report build, installation and usage issues at:
https://github.com/asb-capfan/TkZinc/issues

This software is distributed under the new BSD license.
See Copyright for copyright information.

Authors and contributors:

Tk::Zinc's main author is Patrick Lecoanet (CENA).
Submodules, demos and documentation were developed by Daniel Etienne (CENA),
Christophe Mertz (formerly CENA, then IntuiLab) and Jean-Luc Vinot (CENA),
with contributions from Stéphane Chatty (IntuiLab), Céline Schlienger
(IntuiLab) and Alexandre Lemort (IntuiLab).
Stéphane Conversy (CENA) contributed to the macOS port.
Many others contributed bug reports.
