This site has been retired. For up to date information, see handbook.gnome.org or gitlab.gnome.org.


[Home] [TitleIndex] [WordIndex

1. Application Conventions for GJS

This document aims to build a set of conventions for JS applications using GJS and GObjectIntrospection.

1.1. Rationale

It is believed that the current deployment facilities for GJS apps, ie autotools, bash wrapper scripts (https://git.gnome.org/browse/gnome-documents/tree/src/gnome-documents.in) and sed invocations (https://git.gnome.org/browse/gnome-documents/tree/src/Makefile.am#n26) represent a huge obstacle in making the GJS application platform palatable for newcomers. Additionally, the lack of standardization on the build system hinders the diffusion of pure JS utility / convenience modules.

The goal is to create a standard packaging method for GJS, similar to Python's .

The choice of keeping the autotools stems from the desire of integration with GNOME submodules such as libgd and egg-list-box. While those are temporary and will enter GTK in due time, it is still worthy for free software applications to be able to share submodules easily.

Moreover, so far the autotools have the best support for generating GObjectIntrospection information, and it is sometimes necessary for JS apps to use a private helper library in a compiled language.

1.2. Requirements

1.3. Prior Art

1.4. Specification

The following meta variable are used throughout this document:

This specification is an addition to the Gjs style guide, and it inherits all requirements.

1.4.1. Package layout

1.4.2. Usage

Applications complying with this specification will have one application script, installed in ${prefix}/share/${package-name} (aka ${pkgdatadir}), and named as ${entry-point-name}, without any extension or mangling.

Optionally, one or more symlinks will be placed in ${bindir}, pointing to the appropriate script in ${pkgdatadir} and named in a fashion more suitable for command line usage (usually ${package-tarname}). Alternatively, a script that calls "gapplication launch ${package-name}" can be used.

The application itself will be DBus activated from a script called src/${entry-point-name}, generated from configure substitution of the following ${entry-point-name}.in:

   1 #!@GJS@
   2 imports.package.init({ name: "${package-name}", version: "@PACKAGE_VERSION@", prefix: "@prefix@" });
   3 imports.package.run(${main-module})

Where ${main-module} is a module containing the main() function that will be invoked to start the process. This function should accept a single argument, an array of command line args. The first element in the array will be the full resolved path to the entry point itself (unlike the global ARGV variable for gjs). Also unlike ARGV, it is safe to modify this array.

This main() function should initialize a GApplication whose id is ${entry-point-name}, and do all the work inside the GApplication vfunc handlers.

/!\ Users should refer to https://github.com/gcampax/gtk-js-app for a full example of the build environment.

1.4.3. Runtime support

The following API will be available to applications, through the package.js module.


2024-10-23 10:58