Sanko Robinson [三興]

NAME

FLTK::Notes - Annotated Guide to the Ins and Outs of FLTK

Description

I am actively seeking volunteers to help test and develop this project. Please see the notes on joining the team.

This is a first draft attempt at defining a road map for future development and a behavioral reference for users and third-party developers.

Support and Information Links

Right off the bat, here's a list of some of the important links refered to in this document.

Website and Blog

Eventually, the official website will be http://sanko.github.com/perl-fltk/. There you'll find html versions of all the documentation, examples, the development blog, and links to other resources.

...eventually.

Live support

Eventually, the official means of support for FLTK may be through #fltk on... some IRC network. Probably Freenode. If anyone aside from me decides to show up on a regular basis.

Yeah, ...eventually.

Receive Commit and Issue Tracker Updates

Follow the project on github: http://github.com/sanko/perl-fltk/

Mailinglist

I'd need someone to host it. :\

Issue Tracker

Use http://github.com/sanko/perl-fltk/issues/list for bug tracking. Please include as much information as possible and review the list in the Bug Tracking section below.

Twitter

I announce stable builds and occasionally complain on Twitter: http://twitter.com/FLTKpm

API

[TODO]

API Maturity

Please see the section on API Backward Compatibility.

Documentation Resources

[TODO]

See Also

See also the section on APIDoc.

...vs. the C++ API

For the most part, I have tried to emulate the official interface to FLTK but there are a few areas where I stray (sometimes drastically) from the C++ API Here, I'll list them and (for some) try to explain why.

If a change I mention here chafes you the wrong way, you're free to (within reason) bug me about it until I reconsider. ...and, in turn, I am free to ignore you if I'm busy or just about any other reason. Drop such requests in the issue tracker.

Major Differences

  • choice(...)'s choices (<_<) are shown in the correct order; from left to right.

Minor Differences

System Requirements

If you work with any other setups (VC++, CygFail, etc.) and would like to lend a hand with development please join the team. If you just want to report a bug or help test, that's cool too.

Prerequisites

FLTK requires Alien::FLTK2 (which attempts to build and install a local copy of the fltk libs) is listed as prerequisite in Build.PL so, unless you answer 'no' when prompted, the CPAN shell should automatically install it for you.

Other requirements are listed by system below.

OSs

This is a partial (and currently incomplete) list of OSs/setups known to work or have problems with FLTK. Where possible, workarounds are mentioned.

Mac OS

Absolutly untested. The fltk libs work on MacOS but the last time I had access to an Apple was in 1st grade. I played Number Munchers.

*nix

Before most major changes are uploaded, I run the test suite with the latest Xbuntu (LTS). Assistance (even if only test reports) from BSDs are welcome.

Win32

My primary dev environment is XP Professional with MinGW. If you work with any other setups (VC++, CygFail, etc.) and would like to lend a hand with development and/or testing, please join the team.

GL

[TODO]

Installation

This distribution uses Module::Build for installation, so use the following procedure:

  perl Build.PL
  ./Build
  ./Build test
  ./Build install

See also: Distribution Testing

Installing the FLTK Libraries

Please refer to Alien::FLTK2.

Backward Compatibility

This section lists recent major changes in API or behavior between stable releases. For older news see the Changes file included with this distribution. For detail see the commit logs.

...nothin' has changed yet.

...and yeah, I know this isn't fluff but it may grow too large to put near the top with API.

The Source

Getting the source

[TODO]

GitHub

[TODO]

CPAN

[TODO]

...as a Developer

[TODO]

...as a User

[TODO]

APIDoc

To make life easy, FLTK's documentation is in the xs source files near to whatever is being described. The documentation format is based on the apidoc found in perl's own core. ...why not steal a great idea, amirite?

During the build process, the documentation is pulled from the xs and .pod files are created and installed with the module.

APIDoc format

For folks with an itch to hack or a flair for words and want to help improve the documentation, lines are of the form:

    flags|prereq|return_type|function_name|arg1|arg2|...|argN

 flags are single letters with following meanings:
    D       depreciated code/widget
    E       enum/flag
    F       function rather than an OO method*
    x       experimental and may be removed or changed in a future version
    T[X,Y]  exported by tags :X and :Y
    N       basic functionality has changed since the last major release*
    U       suppress usage example in auto-generated documentation
    H       this is a hidden, internal (hacker only) function
    A       interface or functionality differs from the original API

 prereq are single letters with the following meanings:
    G       requires GL
    X       requires the X Window system
    t       requires pthreads (or Windows)*
    W       requires Windows

* denotes stuff I haven't really given enough thought to and probably haven't used yet.

This format is subject to change.

Contributing

[TODO]

The Development Cycle

This section describes all the behind the scenes stuff that makes FLTK work. Or not work. It depends. If you're interested in assisting with FLTK's development but don't know where to begin, here are a few ideas.

Work, work, work...

[TODO]

Bug Stomping

[TODO]

Also see the section on testing development builds.

Release

[TODO]

The Team

...well, it's currently a team of one. But I'm looking for help. Skip down to the join the team section below.

Join the Team

FLTK is too large for just one person to hack on. If you're XS, C++, or just Perl-adept and would like to help, you can start by forking the project on github: http://github.com/sanko/perl-fltk/. When ready, send me a pull request, I'll look over your changes and get back to you. Minor patches get your name in the changelog. Really major contributions get your name in the Acknowledgments section and an invitation to be a trusted collaborator. Oooo. Ahhh.

As "The Team" grows (assuming anyone helps me out...) the development cycle will grow with it. For now, a trimmed down version of Moose's contribution notes.

Bug Tracking

Found bugs should be reported through FLTK's Issue Tracker. Before creating a new report, please review the following list:

1. Make sure you are using the most recent stable release.
2. Make sure the bug is reproducible.
3. Please write in clear English.
4. Provide "baby steps" to describe exactly how to replicate the bug. Sample code is welcome.
5. Search the list of open and resolved issues to make sure the flaw hasn't already been reported.
7. Look over your report before submission to be sure you've included as much detail as possible. Seriously. Get up, have a drink of water, come back, read over it again to make sure you've included everything you intended, and then submit it.

Testing

More than just about anything else, FLTK needs to be tested. Here are a couple ways you can help with that.

Testing Development Builds

[TODO]

Distribution Testing

Becoming a CPAN Tester is an easy, automatic way to contribute to the quality of your favorite module and CPAN in general. If you would like to contribute automated test reports for FLTK, install CPAN::Reporter from the CPAN shell first:

 $ cpan
 cpan> install CPAN::Reporter
 cpan> reload cpan
 cpan> o conf init test_report
   [...follow the CPAN::Reporter setup prompts...]
 cpan> o conf commit
 cpan> install FLTK

For more on becoming a CPAN Tester and why this is useful, see the CPAN::Reporter documentation and http://cpantesters.org/.

See Also

What are the Versions of FLTK?

http://fltk.org/articles.php?L825+I0+T+P1+Q

Author

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

CPAN ID: SANKO

License and Legal

Copyright (C) 2008-2009 by Sanko Robinson <sanko@cpan.org>

This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See the LICENSE file included with this distribution or http://www.perlfoundation.org/artistic_license_2_0. For clarification, see http://www.perlfoundation.org/artistic_2_0_notes.

When separated from the distribution, all POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See http://creativecommons.org/licenses/by-sa/3.0/us/legalcode. For clarification, see http://creativecommons.org/licenses/by-sa/3.0/us/.




Hosting generously
sponsored by Bytemark