Skip to content

Latest commit

 

History

History
177 lines (125 loc) · 7.34 KB

index.mdwn

File metadata and controls

177 lines (125 loc) · 7.34 KB
Raw

[[!toc]]

Contributions

Perl basics

Standard modules

Testing

Testing in Perl uses a format called the [[Test Anything Protocol|http://testanything.org/]] (or TAP). This is a simple text-based format that outputs test results in a standard way such that the results can be generated by different tools and even stored for later processing.

In order actually run these tests, you need to use the [[prove|https://p3rl.org/prove]] test harness command. Usually you want to run the test files under the t/ directory. By default, test files are just Perl scripts that have the extension .t.

You can do that by running prove -lvr t/.

  • The t/ part tells prove where it to look for test files.
  • The -l option adds the Perl modules under the lib/ directory to the Perl search path (@INC).
  • The -v option runs the tests in verbose mode to give extra information about each test.
  • The -r option recursively loads test files for every directory given.

In order to actually write the tests, look over the documentation for [[Test::Most|https://p3rl.org/Test::Most]] and [[Test::More|https://p3rl.org/Test::More]]. These contain functions for checking for expected conditions in the test code.

[[!template id=youtube v="KAE3qrxBdXs"]]

Release managment

In order to make releases, we use [[Dist::Zilla|https://p3rl.org/Dist::Zilla]]. This is a tool that can extended to do many maintenance tasks such as listing all the dependencies of the code or testing for spelling errors in documentation.

Documentation

Perl documentation is written in a format called [[POD|https://p3rl.org/perlpod]]. It has a simple syntax that can be converted to many other formats such as HTML or manpages. That syntax can be extended by using [[Pod::Weaver|https://p3rl.org/Pod::Weaver]] which acts as a preprocessor that can add additional directives to POD.

Devops

We use virtual machines to test the code under different environments. These virtual machines are configured by using [[Vagrant|https://www.vagrantup.com/]]. See the [[devops|https://github.com/project-renard/devops]] repository for more information.

  • Devel::REPL (TODO)

GTK

GTK+ is the cross-platform GUI toolkit that we use. Instead of writing the GUI code entirely by hand, much of layout is done interactively using the [[Glade|https://glade.gnome.org/]] designer.

GTK+ is a C library. Despite being written in C, it is written in an object-oriented style by using the glib C library. This has the advantage that bindings to a glib-based library can be easily created for languages like Perl, by using something called the [[GObject Introspection|https://wiki.gnome.org/action/show/Projects/GObjectIntrospection]] layer. This is how the Perl bindings to GTK+ are also provided by providing access to that layer using the [[Glib::Object::Introspection|https://p3rl.org/Glib::Object::Introspection]] package as part of the [[GTK-Perl|http://gtk2-perl.sourceforge.net/doc/]] project.

Learning GTK+

If you want to learn how to use Glade, see the [[Charter example|https://github.com/zmughal/learning-gtk/tree/master/charter]] at this repository https://github.com/zmughal/learning-gtk. The code is based off a tutorial written using C, but if you compare the Perl code to the C code, you can see that it is not that much different. This is because most of the GUI defintion is in the Glade XML file which can be shared by both the C version and the Perl version.

Gnome also hosts several tutorials on how to write GTK+ complete applications without using Glade, most of which are written in C: https://developer.gnome.org/gnome-devel-demos/stable/. One of those tutorials has been translated into Perl and is available here: https://github.com/MaxPerl/perl-Gtk3-Tutorial.

If you are trying to figure out how to use a specific widget and having trouble with the Perl syntax, you may want to look at the following examples that showcase individual widgets:

GTK+ documentation

In order to see the documentation for Glib-based libraries (such as Gtk) in a Perl-friendly way, the [[Glib::Object::Introspection|https://p3rl.org/Glib::Object::Introspection]] package comes with called perli11ndoc that shows all the available classes that can be used for that library using Perl syntax.

[[!img gfx/perli11ndoc.png caption="The perli11ndoc tool showing documentation from Gtk3's AccelGroup class."]]

Debuggging GTK

Use GTK_DEBUG="interactive" (see https://developer.gnome.org/gtk3/stable/gtk-running.html).

Creating Perl bindings

There are five approaches to writing bindings for Perl:

  • Writing bindings in C code that links into the Perl interpreter and uses the [[Perl API|https://p3rl.org/perlapi]].

    • Rarely done.
    • Full control of interpreter internals.

  • Writing bindings using a Perl-specific DSL called [[XS|https://p3rl.org/perlxs]] that gets converted to C code (static).

    • The standard approach to writing bindings.
    • Automatically generates C code that allows for setup of Perl API calls.

  • Writing bindings using [[Inline::C|https://p3rl.org/Inline::C]] code that gets converted to XS then C (static).

    • A simple way to automatically generate XS code without having to learn XS syntax.

  • Writing bindings using [[FFI::Platypus|https://p3rl.org/FFI::Platypus]] ([[libffi|https://sourceware.org/libffi/]]-based) to call functions dynamically.

    • A modern approach that avoids having to write C.

  • Automatically generating XS bindings using [[SWIG|http://www.swig.org/]].

    • Common among very large libraries that need to create bindings for multiple languages at once.

Perl internals and XS

Adding native library bindings

Using Inline

[[Inline|https://p3rl.org/Inline]] is a module that allows for creating interfaces to other languages including C, Python, and Java. It simplifies the binding process so that all that is often needed to create a binding is a snippet of code that is included within the Perl code that automatically gets wrapped when the Perl code is loaded.

In order to release code to other systems that do not have Inline installed, there is [[Inline::Module|https://p3rl.org/Inline::Module]] which automatically includes a copy of the Inline module code necessary to build the Inline-based distribution.

Specific notes about third-party libraries

  • [[MuPDF|doc/survey/tool/mupdf]]

Developing on Windows

  • TODO Under construction

For now :