Skip to content
Commits on Source (190)
Hide whitespace changes
Inline Side-by-side
.gitignore
View file @ 6709d722
# SPDX-License-Identifier: MIT OR LGPL-2.0-or-later
# SPDX-FileCopyrightText: 2020 Philip Chimento <philip.chimento@gmail.com>
/tools/node_modules
# artifact from ci-templates:
/container-build-report.xml
.gitlab-ci.yml
View file @ 6709d722
......@@ -2,7 +2,7 @@
# SPDX-FileCopyrightText: 2017 Claudio André <claudioandre.br@gmail.com>
---
include:
- remote: 'https://gitlab.freedesktop.org/freedesktop/ci-templates/-/raw/7ea696055e322cc7aa4bcbe5422b56a198c4bdff/templates/alpine.yml'
- remote: 'https://gitlab.freedesktop.org/freedesktop/ci-templates/-/raw/c5626190ec14b475271288dda7a7dae8dbe0cd76/templates/alpine.yml'
stages:
- prepare
......@@ -14,7 +14,7 @@ stages:
.gjs-alpine:
variables:
FDO_DISTRIBUTION_TAG: '2021-08-18.0'
FDO_DISTRIBUTION_TAG: '2022-07-23.0'
FDO_UPSTREAM_REPO: GNOME/gjs
build-alpine-image:
......@@ -31,7 +31,7 @@ build-alpine-image:
mkdir -p /cwd
.coverage: &coverage
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs91-debug
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs102-debug
variables:
coverage: '/^ lines.*(\d+\.\d+\%)/'
script:
......@@ -44,13 +44,19 @@ build-alpine-image:
artifacts:
name: log_coverage
when: always
reports:
junit: _coverage_build/meson-logs/testlog*.junit.xml
expose_as: 'Coverage Report'
paths:
- _coverage/html/index.html
- _coverage/html
- _coverage_build/meson-logs/*log*.txt
- _coverage_build/meson-logs
.build: &build
when: on_success
artifacts:
reports:
junit: _build/meson-logs/testlog*.junit.xml
name: log
when: always
paths:
......@@ -69,9 +75,9 @@ build-alpine-image:
build_recommended:
<<: *build
stage: source_check
image: registry.gitlab.gnome.org/gnome/gjs:job-1740076_fedora.mozjs91-debug # pinned on purpose
image: registry.gitlab.gnome.org/gnome/gjs:job-2190518_fedora.mozjs102-debug # pinned on purpose
variables:
TEST_OPTS: --verbose --no-stdsplit --print-errorlogs
TEST_OPTS: --verbose --no-stdsplit --print-errorlogs --setup=verbose
except:
- schedules
......@@ -80,10 +86,10 @@ sanitizer_gcc:
stage: test
tags:
- asan # LSAN needs CAP_SYS_PTRACE
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs91-debug
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs102-debug
variables:
CONFIG_OPTS: -Db_sanitize=address,undefined
TEST_OPTS: --timeout-multiplier=3
TEST_OPTS: --timeout-multiplier=3 --setup=verbose
except:
- schedules
......@@ -94,10 +100,10 @@ sanitizer_thread_gcc:
allow_failure: true
tags:
- asan # TSAN needs CAP_SYS_PTRACE
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs91-debug
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs102-debug
variables:
CONFIG_OPTS: -Db_sanitize=thread
TEST_OPTS: --timeout-multiplier=3
TEST_OPTS: --timeout-multiplier=3 --setup=verbose
except:
- schedules
......@@ -107,7 +113,7 @@ sanitizer_thread_gcc:
build_maximal:
<<: *build
stage: test
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs91-debug
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs102-debug
variables:
CC: clang
CXX: clang++
......@@ -123,18 +129,19 @@ build_maximal:
build_minimal:
<<: *build
stage: test
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs91
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs102
variables:
CONFIG_OPTS: >-
-Dbuildtype=release
-Dcairo=disabled -Dreadline=disabled -Dprofiler=disabled
TEST_OPTS: --setup=verbose
except:
- schedules
build_unity:
<<: *build
stage: test
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs91
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs102
variables:
# unity-size here is forced to use an high number to check whether we can
# join all the sources together, but should not be used in real world to
......@@ -142,6 +149,7 @@ build_unity:
CONFIG_OPTS: >-
-Dprofiler=disabled
--unity on --unity-size=10000
TEST_OPTS: --setup=verbose
except:
- schedules
......@@ -245,7 +253,7 @@ pch_check:
iwyu:
when: on_success
stage: source_check
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs91-debug
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs102-debug
script:
- test/test-ci.sh UPSTREAM_BASE
- meson setup _build -Db_pch=false
......@@ -296,7 +304,7 @@ coverage:
iwyu-full:
when: manual
stage: manual
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs91-debug
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs102-debug
script:
- meson setup _build
- ./tools/run_iwyu.sh
......@@ -308,12 +316,12 @@ sanitizer_clang:
stage: manual
tags:
- asan # LSAN needs CAP_SYS_PTRACE
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs91-debug
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs102-debug
variables:
CC: clang
CXX: clang++
CONFIG_OPTS: -Db_sanitize=address,undefined -Db_lundef=false
TEST_OPTS: --timeout-multiplier=3
TEST_OPTS: --timeout-multiplier=3 --setup=verbose
when: manual
except:
- schedules
......@@ -321,7 +329,7 @@ sanitizer_clang:
installed_tests:
<<: *build
stage: manual
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs91-debug
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs102-debug
variables:
CONFIG_OPTS: -Dinstalled_tests=true -Dprefix=/usr
TEST: skip
......@@ -337,7 +345,7 @@ installed_tests:
valgrind:
<<: *build
stage: manual
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs91-debug
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs102-debug
variables:
TEST_OPTS: --setup=valgrind
allow_failure: true
......@@ -349,7 +357,7 @@ valgrind:
zeal_2:
<<: *build
stage: manual
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs91-debug
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs102-debug
variables:
TEST_OPTS: --setup=extra_gc
when: manual
......@@ -359,7 +367,7 @@ zeal_2:
zeal_4:
<<: *build
stage: manual
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs91-debug
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs102-debug
variables:
TEST_OPTS: --setup=pre_verify
when: manual
......@@ -369,7 +377,7 @@ zeal_4:
zeal_11:
<<: *build
stage: manual
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs91-debug
image: registry.gitlab.gnome.org/gnome/gjs:fedora.mozjs102-debug
variables:
TEST_OPTS: --setup=post_verify
when: manual
......@@ -380,7 +388,7 @@ zeal_11:
# Create CI Docker Images #
#############################################
.Docker image template: &create_docker_image
image: registry.freedesktop.org/freedesktop/ci-templates/x86_64/buildah:2020-10-30.1
image: quay.io/freedesktop.org/ci-templates:container-build-base-2022-05-25.0
stage: deploy
only:
variables:
......@@ -416,11 +424,23 @@ fedora.mozjs91:
variables:
<<: *docker_variables
DOCKERFILE: test/extra/Dockerfile
ARGS: --build-arg MOZJS_BUILDDEPS=mozjs78
fedora.mozjs91-debug:
<<: *create_docker_image
variables:
<<: *docker_variables
DOCKERFILE: test/extra/Dockerfile.debug
ARGS: --build-arg MOZJS_BUILDDEPS=mozjs78
fedora.mozjs102:
<<: *create_docker_image
variables:
<<: *docker_variables
DOCKERFILE: test/extra/Dockerfile
ARGS: --build-arg MOZJS_BRANCH=mozjs102 --build-arg MOZJS_BUILDDEPS=mozjs91
fedora.mozjs102-debug:
<<: *create_docker_image
variables:
<<: *docker_variables
DOCKERFILE: test/extra/Dockerfile.debug
ARGS: --build-arg MOZJS_BRANCH=mozjs102 --build-arg MOZJS_BUILDDEPS=mozjs91
NEWS
View file @ 6709d722
Version 1.74.0
--------------
- Many improvements to the examples and documentation.
- Build fixes for Windows.
- Overrides to certain non-introspectable functions that will now gracefully
throw an exception instead of crashing.
- Closed bugs and merge requests:
* Various maintenance [!786, Philip Chimento]
* http example not reliable, relies on server provided content-length. [#498,
!787, Andy Holmes]
* Gio set_attribute SIGSEGV (Address boundary error) [#496, !788, Philip
Chimento]
* Fix Visual Studio builds after migration to SpiderMonkey 102.x [!789,
Chun-wei Fan]
* Update Visual Studio build instructions [!791, Chun-wei Fan]
* doc: reformat for better scraping with DevDocs [!792, Andy Holmes]
* doc: Update Home [!793, Sonny Piers]
* GLib: override GThread functions [!795, Andy Holmes]
Version 1.73.90
---------------
- Skipped.
Version 1.72.3
--------------
- Fix for crash after build against libffi 3.4.2 ported from the development
branch.
Version 1.73.2
--------------
- New JavaScript features! This version of GJS is based on SpiderMonkey 102, an
upgrade from the previous ESR (Extended Support Release) of SpiderMonkey 91.
Here are the highlights of the new JavaScript features.
For more information, look them up on MDN or devdocs.io.
* New APIs
+ The `Object.hasOwn()` static method can be used as an easier replacement
for `Object.prototype.hasOwnProperty.call(...)`.
+ `Intl.supportedValuesOf()` lets you enumerate which calendars, currencies,
collation strategies, numbering systems, time zones, and units are
available for internationalization.
- It's now possible to use `GObject.BindingGroup.prototype.bind_full()` with JS
functions. Previously this method was unusable in JS.
- Gio.FileEnumerator is now iterable, both synchronously (with for-of or array
spread syntax) and asynchronously (with for-await-of).
- Performance improvements in the built-in `imports.signals` module.
- Many improvements to the examples and documentation.
- Closed bugs and merge requests:
* Spidermonkey 102 [#487, !765, !785, Evan Welsh, Philip Chimento]
* Object connections / signal emissions optimizations [#485, !758, Marco
Trevisan]
* tests/Gio: Cleanup Gio._promisify [!767, Marco Trevisan]
* Include JUnit reports in builds [!768, Marco Trevisan]
* Integrate pretty print to the debugger [!769, Nasah Kuma]
* doc: Edit GJS description [!771, Sonny Piers]
* doc: note the version `constructor()` became supported [!774, Andy Holmes]
* build: disable sysprof agent for subproject fallback [!775, Christian
Hergert]
* Update CI images [!776, !777, !778, Philip Chimento]
* GListModel.get_n_items returns garbage value [#493, !779, Florian Müllner]
* Add override for g_binding_group_bind_full() [!780, Florian Müllner]
* doc: Modernize examples [!781, Sonny Piers]
* doc: Document byteArray deprecation and migration [!782, Sonny Piers]
* doc: add simple Gtk.TickCallback example [!783, Andy Holmes]
* Make GFileEnumerator iterable and async iterable [!784, Sonny Piers]
Version 1.72.2
--------------
......@@ -7,6 +85,58 @@ Version 1.72.2
* gi/arg-cache.cpp: Fix building on Visual Studio [!772, Chun-wei Fan]
* doc: Reflect support for constructor with GObject [!773, Sonny Piers]
Version 1.73.1
--------------
- The interactive interpreter now displays its output more intelligently,
pretty-printing the properties and values of objects based on their type. This
improvement also applies to the log() and logError() functions.
- New API: DBus proxy classes now include methods named with the suffix 'Async',
which perform async calls to DBus APIs and return Promises. This is in
addition to the existing suffixes 'Sync' (for blocking calls) and 'Remote'
(for async calls with callbacks.)
- There is an override for Gio.ActionMap.prototype.add_action_entries().
Previously this method wouldn't work because it required an array of
Gio.ActionEntry objects, which are not possible to construct in GJS. Now it
can be used with an array of plain objects. (e.g. `this.add_action_entries([
{name: 'open', activate() { ... }}]);`
- GJS is now compatible with libffi 3.4.2 and later. All earlier versions of GJS
are not compatible with libffi 3.4.2 and later unless libffi is built with the
--disable-exec-static-tramp flag.
- GJS now requires Meson 0.54 to build.
- Closed bugs and merge requests:
* Verbose Object Print Output [#107, !587, Nasah Kuma]
* Add support for JS async calls in DBusProxyWrapper [!731, Sergio Costas]
* Crash after build against libffi 3.4.2 [#428, !737, Evan Welsh]
* Handle reference cycles in new console pretty print function [#469, !739,
Nasah Kuma]
* Gnome-Shell 42 - crash after login (general protection fault) [#479, !740,
Xi Ruoyao]
* Various maintenance [!741, Philip Chimento]
* jsapi-util-strings: Ignore locale to compute the upper case of a char (i.e.
fix implicit properties on Turkish locale) [!742, Marco Trevisan]
* Dockerfile: Install Turkish locale in CI for UTF-8 locale too [!743, Marco
Trevisan]
* Improve pretty-print output for GObject-introspected objects [#476, !744,
Nasah Kuma]
* Expose pretty print function to tests [!745, Nasah Kuma]
* build: track changes to Sysprof meson options [!747, Christian Hergert]
* Make Gio.ActionMap.add_action_entries work [#407, !749, Sonny Piers]
* Make DBus session and system props non-enumerable [!750, Sonny Piers]
* gi/arg-inl: Mark the arg functions as constexpr [!752, Marco Trevisan]
* build: Do not use verbose GJS debug logging in tests by default [!753, Marco
Trevisan]
* minijasmine: Print test JS errors output if any [!754, Marco Trevisan]
* doc: document the existence of the console object in GJS [!759, Andy Holmes]
* arg-cache: Use a switch to select the not-introspectable error [!762, Marco
Trevisan]
* log_set_writer_func is not safe to use [#481, !766, Evan Welsh]
Version 1.72.1
--------------
......@@ -28,6 +158,26 @@ Version 1.72.0
- No changes from release candidate 1.71.90.
Version 1.70.2
--------------
- Build and compatibility fixes backported from the development branch.
- Closed bugs and merge requests:
* package: Reverse order of running-from-source checks [!734, Philip Chimento]
- Fix build error on Darwin [Evan Miller]
Version 1.68.6
--------------
- Build and compatibility fixes backported from the development branch.
- Closed bugs and merge requests:
* package: Reverse order of running-from-source checks [!734, Philip Chimento]
- Fix build error on Darwin [Evan Miller]
Version 1.71.90
---------------
......
README.MSVC.md
View file @ 6709d722
Instructions for building GJS on Visual Studio or clang-cl
==========================================================
Building the GJS on Windows is now supported using Visual Studio
versions 2019 or later with or without clang-cl in both 32-bit and
64-bit (x64) flavors, via Meson. It should be noted that a
versions 2019 16.5.x or later with or without clang-cl in both 32-bit
and 64-bit (x64) flavors, via Meson. It should be noted that a
recent-enough Windows SDK from Microsoft is still required if using
clang-cl, as we will still use items from the Windows SDK.
Recent official binary installers of CLang (which contains clang-cl)
from the LLVM website are known to work to build SpiderMonkey 91 and
from the LLVM website are known to work to build SpiderMonkey 102 and
GJS.
You will need the following items to build GJS using Visual Studio
or clang-cl (they can be built with Visual Studio 2015 or later,
unless otherwise noted):
-SpiderMonkey 91.x (mozjs-91). This must be built with clang-cl as
-SpiderMonkey 102.x (mozjs-102). This must be built with clang-cl as
the Visual Studio compiler is no longer supported for building this.
Please see the below section carefully on this...
-GObject-Introspection (G-I) 1.61.2 or later
......@@ -44,8 +44,8 @@ for the suitable release series of SpiderMonkey that corresponds to
the GJS version that is being built, as GJS depends on ESR (Extended
Service Release, a.k.a Long-term support) releases of SpiderMonkey.
You may also be able to obtain the SpiderMonkey 91.x sources via the
FireFox (ESR) or Thunderbird 91.x sources, in $(srcroot)/js.
You may also be able to obtain the SpiderMonkey 102.x sources via the
FireFox (ESR) or Thunderbird 102.x sources, in $(srcroot)/js.
Please do note that the build must be done carefully, in addition to the
official instructions that are posted on the Mozilla website:
......@@ -53,39 +53,40 @@ official instructions that are posted on the Mozilla website:
https://firefox-source-docs.mozilla.org/js/build.html
You will need to create a .mozconfig file that will describe your build
options for the build in the root directory of the Firefox/ThunderBird 91.x
options for the build in the root directory of the Firefox/ThunderBird 102.x
sources. A sample content of the .mozconfig file can be added as follows:
```
ac_add_options --enable-application=js
mk_add_options MOZ_MAKE_FLAGS=-j12
mk_add_options JS_STANDALONE=1
ac_add_options --target=x86_64-pc-mingw32
ac_add_options --host=x86_64-pc-mingw32
ac_add_options --disable-tests
ac_add_options --enable-optimize
ac_add_options --disable-debug
ac_add_options --disable-jemalloc
ac_add_options --prefix=c:/software.b/mozjs91.bin
ac_add_options --prefix=c:/software.b/mozjs102.bin
```
An explanation of the lines above:
* `ac_add_options --enable-application=js`: This line is absolutely required, to build SpiderMonkey standalone
* `mk_add_options MOZ_MAKE_FLAGS=-j12`: MOZ_MAKE_FLAGS=-jX means X number of parallel processes for the build
* `mk_add_options JS_STANDALONE=1`: Enforce building SpiderMonkey standalone (could be optional)
* `ac_add_options --target=x86_64-pc-mingw32`: Target architecture, replace `x86_64` with `aarch64` for ARM64 builds, and with `i686` for 32-bit x86 builds.
* `ac_add_options --host=x86_64-pc-mingw32`: Use this as-is, unless building on a 32-bit compiler (replace `x86_64` with `i686`; not recommended)
* `ac_add_options --disable-tests`: Save some build time
* `ac_add_options --enable-optimize`: Use for release builds of SpiderMonkey. Use `--disable-optimize` instead if building with `--enable-debug`
* `ac_add_options --enable-debug`: Include debugging functions, for debug builds. Use `--disable-debug` instead if building with `--enable-optimize`
* `ac_add_options --disable-jemalloc`: This is absolutely needed, otherwise GJS will not build and run correctly
* `ac_add_options --prefix=c:/software.b/mozjs91.bin`: Some installation path, change as needed
* `ac_add_options --prefix=c:/software.b/mozjs102.bin`: Some installation path, change as needed
If your GJS build crashes upon launch, use Dependency Walker to ensure that
mozjs-91.dll does not depend on mozglue.dll! If it does, or if GJS fails to
mozjs-102.dll does not depend on mozglue.dll! If it does, or if GJS fails to
link with missing arena_malloc() and friends symbols, you have built SpiderMoney
incorrectly and will need to rebuild SpiderMonkey (with the build options as
noted above) and retry the build.
noted above) and retry the build. Because SpiderMonkey needs to be built
without jemalloc, enclose the entire `DllMain()` implementation in
`$(srcroot)/js/src/jsapi.cpp` with `#if 0` ... `#endif`, otherwise
SpiderMonkey will fail to link.
Please also check that `--enable-optimize` is *not* used with `--enable-debug`.
You should explicitly enable one and disable the other, as `--enable-debug`
......@@ -119,17 +120,28 @@ $(buildroot)/dist/include. Note that for PDB files and .lib files,
you will need to search for them in $(buildroot),
where the PDB file names match the filenames for the DLLs/EXEs in
$(buildroot)/dist/bin, and you will need to look for the following .lib files:
-mozjs-91.lib
-mozjs-102.lib
-js_static.lib (optional)
Due to some bugs that are not yet resolved in upstream SpiderMonkey 102.x,
you may need to do the following after running `./mach build install` and
before attempting to build GJS itself:
* Copy `$(builddir)/dist/include/js/ProfilingCategoryList.h` to
`$(PREFIX)\include\mozjs-102\js`.
* Change `$(PREFIX)\include\mozjs-102\mozilla\EnumSet.h` and change line
329 from `static constexpr size_t kMaxBits = EnumSet().MaxBits();`
to `size_t kMaxBits = EnumSet().MaxBits();`.
You may want to put the .lib's and DLLs/EXEs into $(PREFIX)\lib and
$(PREFIX)\bin respectively, and put the headers into
$(PREFIX)\include\mozjs-91 for convenience.
$(PREFIX)\include\mozjs-102 for convenience.
You will need to place the generated mozjs-91.pc pkg-config file into
You will need to place the generated mozjs-102.pc pkg-config file into
$(PREFIX)\lib\pkgconfig and ensure that pkg-config can find it by
setting PKG_CONFIG_PATH. Ensure that the 'includedir' and 'libdir'
in there is correct so that the mozjs-91.pc can be used correctly in
in there is correct so that the mozjs-102.pc can be used correctly in
Visual Studio/clang-cl builds, and replace the `-isystem` with `-I` if
building GJS with Visual Studio. You will also need to ensure that the
existing GObject-Introspection installation (if used) is on the same
......@@ -158,7 +170,9 @@ meson <path_to_gjs_sources> --buildtype=... --prefix=<some_prefix> -Dskip_dbus_t
see the Meson documentation for the values accepted by buildtype)
You may want to view the build options after the configuration succeeds
by using 'meson configure'
by using 'meson configure'. You may need to set the envvar:
`SETUPTOOLS_USE_DISTUTILS=stdlib` for the introspection step to proceed
successfully. A fix for this is being investigated.
When the configuration succeeds, run:
ninja
......
README.md
View file @ 6709d722
......@@ -6,13 +6,17 @@
[![License](https://img.shields.io/badge/License-LGPL%20v2%2B-blue.svg)](https://gitlab.gnome.org/GNOME/gjs/blob/HEAD/COPYING)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://gitlab.gnome.org/GNOME/gjs/blob/HEAD/COPYING)
JavaScript bindings for GNOME
GNOME JavaScript
=============================
GJS is a JavaScript runtime built on
[Firefox's SpiderMonkey JavaScript engine](https://spidermonkey.dev/) and
the [GNOME platform libraries](https://developer.gnome.org/).
Use the GNOME platform libraries in your JavaScript programs.
GJS powers GNOME Shell, Polari, GNOME Documents, and many other apps.
Under the hood it uses SpiderMonkey, Mozilla's JavaScript engine
originally developed for Firefox.
GJS powers GNOME Shell, Maps, Characters, Sound Recorder and many other apps.
If you would like to learn more or get started with GJS, head over to the [documentation](./doc/Home.md).
## Installation
......
build/flatpak/org.gnome.GjsConsole.json
View file @ 6709d722
......@@ -11,10 +11,16 @@
"sdk": "org.gnome.Sdk",
"command": "gjs-console",
"finish-args": [
"--socket=x11",
"--share=ipc",
"--socket=fallback-x11",
"--socket=wayland",
"--device=dri",
"--share=network",
"--filesystem=host"
"--filesystem=host",
"--filesystem=home",
"--socket=session-bus",
"--socket=system-bus",
"--socket=pulseaudio"
],
"modules": [
{
......
debian/changelog
View file @ 6709d722
gjs (1.74.0-0ubuntu1) jammy-security; urgency=medium
* New upstream major release (LP: #1993214)
* Build against mozjs102
* debian/libgjs0g.symbols: Add new symbol
-- Jeremy Bicha <jbicha@ubuntu.com> Mon, 17 Oct 2022 14:16:23 -0400
gjs (1.72.2-0ubuntu1) jammy; urgency=medium
* New upstream release (LP: #1981722)
......
debian/control
View file @ 6709d722
......@@ -18,7 +18,7 @@ Build-Depends: debhelper-compat (= 13),
libgirepository1.0-dev (>= 1.64),
gir1.2-gtk-3.0,
gobject-introspection (>= 1.64),
libmozjs-91-dev (>= 91.3.0),
libmozjs-102-dev,
libreadline-dev,
meson (>= 0.50.0),
dbus <!nocheck>,
......@@ -92,7 +92,7 @@ Depends: ${misc:Depends},
libgjs0g (= ${binary:Version}),
libgirepository1.0-dev (>= 1.64),
libcairo2-dev,
libmozjs-91-dev (>= 91.3.0),
libmozjs-102-dev,
Description: Mozilla-based javascript bindings for the GNOME platform
Makes it possible for applications to use all of GNOME's platform
libraries using the JavaScript language. It's mainly based on the
......
debian/control.in
View file @ 6709d722
......@@ -14,7 +14,7 @@ Build-Depends: debhelper-compat (= 13),
libgirepository1.0-dev (>= 1.64),
gir1.2-gtk-3.0,
gobject-introspection (>= 1.64),
libmozjs-91-dev (>= 91.3.0),
libmozjs-102-dev,
libreadline-dev,
meson (>= 0.50.0),
dbus <!nocheck>,
......@@ -88,7 +88,7 @@ Depends: ${misc:Depends},
libgjs0g (= ${binary:Version}),
libgirepository1.0-dev (>= 1.64),
libcairo2-dev,
libmozjs-91-dev (>= 91.3.0),
libmozjs-102-dev,
Description: Mozilla-based javascript bindings for the GNOME platform
Makes it possible for applications to use all of GNOME's platform
libraries using the JavaScript language. It's mainly based on the
......
debian/libgjs0g.symbols
View file @ 6709d722
......@@ -36,6 +36,7 @@ libgjs.so.0 libgjs0g #MINVER#
gjs_dumpstack@Base 1.63.90
gjs_error_quark@Base 1.63.90
gjs_format_int_alternative_output@Base 1.63.90
gjs_g_binding_group_bind_full@Base 1.73.2
gjs_g_object_bind_property_full@Base 1.70.0
gjs_get_js_version@Base 1.63.90
gjs_gobject_class_info@Base 1.70.0
......
doc/ByteArray.md
View file @ 6709d722
The `imports.byteArray` module was originally based on an
ECMAScript 4 proposal that was never adopted.
Now that ES6 has typed arrays, we use `Uint8Array` to represent byte
arrays in GJS and add some extra functions for conversion to and from
strings and `GLib.Bytes`.
# ByteArray
Unlike the old custom `ByteArray`, `Uint8Array` is not resizable. The main
goal for most gjs users will be to shovel bytes between various C
APIs, for example reading from an IO stream and then pushing the bytes
into a parser. Actually manipulating bytes in JS is likely to be
pretty rare, and slow ... an advantage of the
gjs/gobject-introspection setup is that stuff best done in C, like
messing with bytes, can be done in C.
The `ByteArray` module provides a number of utilities for converting between
[`GLib.Bytes`][gbytes] object, `String` values and `Uint8Array` objects.
---
It was originally based on an ECMAScript 4 proposal that was never adopted, but
now that ES6 has typed arrays, we use the standard `Uint8Array` to represent
byte arrays in GJS.
## ByteArray Functions ##
The primary use for most GJS users will be to exchange bytes between various C
APIs, like reading from an IO stream and then pushing the bytes into a parser.
Actually manipulating bytes in GJS is likely to be pretty slow and fortunately
rarely necessary. An advantage of the GJS and GObject-Introspection setup is
that most of the tasks best done in C, like messing with bytes, can be.
The ByteArray module has the following functions:
[gbytes]: https://gjs-docs.gnome.org/glib20/glib.bytes
### `fromString(s:String, encoding:String):Uint8Array` ###
#### Import
> Attention: This module is not available as an ECMAScript Module
The `ByteArray` module is available on the global `imports` object:
```js
const ByteArray = imports.byteArray;
```
### ByteArray.fromString(string, encoding)
> Deprecated: Use [`TextEncoder.encode()`][textencoder-encode] instead
Type:
* Static
Parameters:
* string (`String`) — A string to encode
* encoding (`String`) — Optional encoding of `string`
Returns:
* (`Uint8Array`) — A byte array
Convert a String into a newly constructed `Uint8Array`; this creates a
new `Uint8Array` of the same length as the String, then assigns each
`Uint8Array` entry the corresponding byte value of the String encoded
according to the given encoding (or UTF-8 if not given).
### `toString(a:Uint8Array, encoding:String):String` ###
[textencoder-encode]: https://gjs-docs.gnome.org/gjs/encoding.md#textencoder-encode
### ByteArray.toString(byteArray, encoding)
> Deprecated: Use [`TextDecoder.decode()`][textdecoder-decode] instead
Type:
* Static
Parameters:
* byteArray (`Uint8Array`) — A byte array to decode
* encoding (`String`) — Optional encoding of `byteArray`
Returns:
* (`String`) — A string
Converts the `Uint8Array` into a literal string. The bytes are
interpreted according to the given encoding (or UTF-8 if not given).
The resulting string is guaranteed to round-trip back into an identical ByteArray by passing the result to `ByteArray.fromString()`, i.e., `b === ByteArray.fromString(ByteArray.toString(b, encoding), encoding)`.
The resulting string is guaranteed to round-trip back into an identical
ByteArray by passing the result to `ByteArray.fromString()`. In other words,
this check is guaranteed to pass:
```js
const original = ByteArray.fromString('foobar');
const copy = ByteArray.fromString(ByteArray.toString(original));
console.assert(original.every((value, index) => value === copy[index]));
```
### `fromGBytes(b:GLib.Bytes):Uint8Array` ###
[textdecoder-decode]: https://gjs-docs.gnome.org/gjs/encoding.md#textdecoder-decode
### ByteArray.fromGBytes(bytes)
> Deprecated: Use [`GLib.Bytes.toArray()`][gbytes-toarray] instead
Type:
* Static
Parameters:
* bytes (`GLib.Bytes`) — A [`GLib.Bytes`][gbytes] to convert
Returns:
* (`Uint8Array`) — A new byte array
Convert a [`GLib.Bytes`][gbytes] instance into a newly constructed `Uint8Array`.
Convert a `GLib.Bytes` instance into a newly constructed `Uint8Array`.
The contents are copied.
### `toGBytes(a:Uint8Array):GLib.Bytes` ###
[gbytes]: https://gjs-docs.gnome.org/glib20/glib.bytes
[gbytes-toarray]: https://gjs-docs.gnome.org/gjs/overrides.md#glib-bytes-toarray
### ByteArray.toGBytes(byteArray)
> Deprecated: Use [`new GLib.Bytes()`][gbytes] instead
Type:
* Static
Parameters:
* byteArray (`Uint8Array`) — A byte array to convert
Returns:
* (`GLib.Bytes`) — A new [`GLib.Bytes`][gbytes]
Converts the `Uint8Array` into a [`GLib.Bytes`][gbytes] instance.
Converts the `Uint8Array` into a `GLib.Bytes` instance.
The contents are copied.
[gbytes]: https://gjs-docs.gnome.org/glib20/glib.bytes
doc/Console.md 0 → 100644
View file @ 6709d722
# Console
GJS implements the [WHATWG Console][whatwg-console] specification, with some
changes to accommodate GLib.
In particular, log severity is mapped to [`GLib.LogLevelFlags`][gloglevelflags]
and some methods are not implemented:
* `console.profile()`
* `console.profileEnd()`
* `console.timeStamp()`
#### Import
The functions in this module are available globally, without import.
[whatwg-console]: https://console.spec.whatwg.org/
[gloglevelflags]: https://gjs-docs.gnome.org/glib20/glib.loglevelflags
### console.assert(condition, ...data)
Type:
* Static
Parameters:
* condition (`Boolean`) — A boolean condition which, if `false`, causes the log
to print
* data (`Any`) — Formatting substitutions, if applicable
> New in GJS 1.70 (GNOME 41)
Logs a critical message if the condition is not truthy.
See [`console.error()`](#console-error) for additional information.
### console.clear()
Type:
* Static
> New in GJS 1.70 (GNOME 41)
Resets grouping and clears the terminal on systems supporting ANSI terminal
control sequences.
In file-based stdout or systems which do not support clearing, `console.clear()`
has no visual effect.
### console.count(label)
Type:
* Static
Parameters:
* label (`String`) — Optional label
> New in GJS 1.70 (GNOME 41)
Logs how many times `console.count()` has been called with the given `label`.
See [`console.countReset()`](#console-countreset) for resetting a count.
### console.countReset(label)
Type:
* Static
Parameters:
* label (`String`) — The unique label to reset the count for
> New in GJS 1.70 (GNOME 41)
Resets a counter used with `console.count()`.
### console.debug(...data)
Type:
* Static
Parameters:
* data (`Any`) — Formatting substitutions, if applicable
> New in GJS 1.70 (GNOME 41)
Logs a message with severity equal to
[`GLib.LogLevelFlags.LEVEL_DEBUG`][gloglevelflagsdebug].
[gloglevelflagsdebug]: https://gjs-docs.gnome.org/glib20/glib.loglevelflags#default-level_debug
### console.dir(item, options)
Type:
* Static
Parameters:
* item (`Object`) — The item to display
* options (`undefined`) — Additional options for the formatter. Unused in GJS.
> New in GJS 1.70 (GNOME 41)
Resurively display all properties of `item`.
### console.dirxml(...data)
Type:
* Static
Parameters:
* data (`Any`) — Formatting substitutions, if applicable
> New in GJS 1.70 (GNOME 41)
Alias for [`console.log()`](#console-log)
### console.error(...data)
Type:
* Static
Parameters:
* data (`Any`) — Formatting substitutions, if applicable
> New in GJS 1.70 (GNOME 41)
Logs a message with severity equal to
[`GLib.LogLevelFlags.LEVEL_CRITICAL`][gloglevelflagscritical].
Does not use [`GLib.LogLevelFlags.LEVEL_ERROR`][gloglevelflagserror] to avoid
asserting and forcibly shutting down the application.
[gloglevelflagscritical]: https://gjs-docs.gnome.org/glib20/glib.loglevelflags#default-level_critical
[gloglevelflagserror]: https://gjs-docs.gnome.org/glib20/glib.loglevelflags#default-level_error
### console.group(...data)
Type:
* Static
Parameters:
* data (`Any`) — Formatting substitutions, if applicable
> New in GJS 1.70 (GNOME 41)
Creates a new inline group in the console log, causing any subsequent console
messages to be indented by an additional level, until `console.groupEnd()` is
called.
### console.groupCollapsed(...data)
Type:
* Static
Parameters:
* data (`Any`) — Formatting substitutions, if applicable
> New in GJS 1.70 (GNOME 41)
Alias for [`console.group()`](#console-group)
### console.groupEnd()
Type:
* Static
> New in GJS 1.70 (GNOME 41)
Exits the current inline group in the console log.
### console.info(...data)
Type:
* Static
Parameters:
* data (`Any`) — Formatting substitutions, if applicable
> New in GJS 1.70 (GNOME 41)
Logs a message with severity equal to
[`GLib.LogLevelFlags.LEVEL_INFO`][gloglevelflagsinfo].
[gloglevelflagsinfo]: https://gjs-docs.gnome.org/glib20/glib.loglevelflags#default-level_info
### console.log(...data)
Type:
* Static
Parameters:
* data (`Any`) — Formatting substitutions, if applicable
> New in GJS 1.70 (GNOME 41)
Logs a message with severity equal to
[`GLib.LogLevelFlags.LEVEL_MESSAGE`][gloglevelflagsmessage].
[gloglevelflagsmessage]: https://gjs-docs.gnome.org/glib20/glib.loglevelflags#default-level_message
### console.table(tabularData, options)
> Note: This is an alias for [`console.log()`](#console-log) in GJS
Type:
* Static
Parameters:
* tabularData (`Any`) — Formatting substitutions, if applicable
* properties (`undefined`) — Unsupported in GJS
> New in GJS 1.70 (GNOME 41)
Logs a message with severity equal to
[`GLib.LogLevelFlags.LEVEL_MESSAGE`][gloglevelflagsmessage].
[gloglevelflagsmessage]: https://gjs-docs.gnome.org/glib20/glib.loglevelflags#default-level_message
### console.time(label)
Type:
* Static
Parameters:
* label (`String`) — unique identifier for this action, pass to
`console.timeEnd()` to complete
> New in GJS 1.70 (GNOME 41)
Starts a timer you can use to track how long an operation takes.
### console.timeEnd(label)
Type:
* Static
Parameters:
* label (`String`) — unique identifier for this action
> New in GJS 1.70 (GNOME 41)
Logs the time since the last call to `console.time(label)` and completes the
action.
Call `console.time(label)` again to re-measure.
### console.timeLog(label, ...data)
Type:
* Static
Parameters:
* label (`String`) — unique identifier for this action, pass to
`console.timeEnd()` to complete
* data (`Any`) — Formatting substitutions, if applicable
> New in GJS 1.70 (GNOME 41)
Logs the time since the last call to `console.time(label)` where `label` is the
same.
### console.trace(...data)
Type:
* Static
Parameters:
* data (`Any`) — Formatting substitutions, if applicable
> New in GJS 1.70 (GNOME 41)
Outputs a stack trace to the console.
### console.warn(...data)
Type:
* Static
Parameters:
* data (`Any`) — Formatting substitutions, if applicable
> New in GJS 1.70 (GNOME 41)
Logs a message with severity equal to
[`GLib.LogLevelFlags.LEVEL_WARNING`][gloglevelflagswarning].
[gloglevelflagswarning]: https://gjs-docs.gnome.org/glib20/glib.loglevelflags#default-level_warning
## Log Domain
> New in GJS 1.70 (GNOME 41)
The log domain for the default global `console` object is set to `"Gjs-Console"`
by default, but can be changed if necessary. The three symbols of interest are
`setConsoleLogDomain()`, `getConsoleLogDomain()` and `DEFAULT_LOG_DOMAIN`.
You can import these symbols and modify the log domain like so:
```js
import { setConsoleLogDomain, getConsoleLogDomain, DEFAULT_LOG_DOMAIN } from 'console';
// Setting the log domain
setConsoleLogDomain('my.app.id');
// expected output: my.app.id-Message: 12:21:17.899: cool
console.log('cool');
// Checking and resetting the log domain
if (getConsoleLogDomain() !== DEFAULT_LOG_DOMAIN)
setConsoleLogDomain(DEFAULT_LOG_DOMAIN);
// expected output: Gjs-Console-Message: 12:21:17.899: cool
console.log('cool');
```
doc/ESModules.md
View file @ 6709d722
# Modules: ECMAScript modules
# ECMAScript Modules
> _This documentation is inspired by [Node.js' documentation](https://github.com/nodejs/node/blob/HEAD/doc/api/esm.md)
> on ECMAScript modules._
......@@ -223,7 +223,7 @@ or if you want the path for the current file or directory
```js
import GLib from 'gi://GLib';
const [filename] = GLib.filename_from_uri(import.meta.url);
const dirname = GLib.path_get_dirname(path);
const dirname = GLib.path_get_dirname(filename);
```
## Interoperability with legacy `imports` modules
......
doc/Encoding.md 0 → 100644
View file @ 6709d722
# Encoding
GJS implements the [WHATWG Encoding][whatwg-encoding] specification.
The `TextDecoder` interface represents a decoder for a specific text encoding,
such as `UTF-8`, `ISO-8859-2`, `KOI8-R`, `GBK`, etc. A decoder takes a list of
bytes as input and emits a list of code points.
The `TextEncoder` interface takes a list of code points as input and emits a
list of UTF-8 bytes.
#### Import
The functions in this module are available globally, without import.
[whatwg-encoding]: https://encoding.spec.whatwg.org/
### TextDecoder(utfLabel, options)
Type:
* Static
Parameters:
* utfLabel (`Number`) — Optional string, defaulting to `"utf-8"`, containing the
label of the encoder.
* options (`Object`) — Optional dictionary with the `Boolean` property `fatal`,
corresponding to the `TextDecoder.fatal` property.
Returns:
* (`TextDecoder`) — A newly created `TextDecoder` object
> New in GJS 1.70 (GNOME 41)
The `TextDecoder()` constructor returns a newly created `TextDecoder` object for
the encoding specified in parameter.
If the value for `utfLabel` is unknown, or is one of the two values leading to a
'replacement' decoding algorithm ("iso-2022-cn" or "iso-2022-cn-ext"), a
`RangeError` is thrown.
### TextDecoder.encoding
Type:
* `String`
> New in GJS 1.70 (GNOME 41)
The `TextDecoder.encoding` read-only property returns a string containing the
name of the decoding algorithm used by the specific decoder.
### TextDecoder.fatal
Type:
* `Boolean`
> New in GJS 1.70 (GNOME 41)
The fatal property of the `TextDecoder` interface is a `Boolean` indicating
whether the error mode is fatal. If this value is `true`, the processed text
cannot be decoded because of malformed data. If this value is `false` malformed
data is replaced with placeholder characters.
### TextDecoder.ignoreBOM
Type:
* `Boolean`
> New in GJS 1.70 (GNOME 41)
The `ignoreBOM` property of the `TextDecoder` interface is a `Boolean`
indicating whether the byte order mark is ignored.
### TextDecoder.decode(buffer, options)
Parameters:
* buffer (`Number`) — Optional `ArrayBuffer`, a `TypedArray` or a `DataView`
object containing the text to decode.
* options (`Object`) — Optional dictionary with the `Boolean` property `fatal`,
indicating that additional data will follow in subsequent calls to `decode()`.
Set to `true` if processing the data in chunks, and `false` for the final
chunk or if the data is not chunked. It defaults to `false`.
Returns:
* (`String`) — A string result
> New in GJS 1.70 (GNOME 41)
The `TextDecode.decode()` method returns a string containing the text, given in
parameters, decoded with the specific method for that `TextDecoder` object.
### TextEncoder()
Type:
* Static
> New in GJS 1.70 (GNOME 41)
The `TextEncoder()` constructor returns a newly created `TextEncoder` object
that will generate a byte stream with UTF-8 encoding.
### TextEncoder.encoding
Type:
* `String`
> New in GJS 1.70 (GNOME 41)
The `TextEncoder.encoding` read-only property returns a string containing the
name of the encoding algorithm used by the specific encoder.
It can only have the following value `utf-8`.
### TextEncoder.encode(string)
Parameters:
* string (`String`) — A string containing the text to encode
Returns:
* (`Uint8Array`) — A `Uint8Array` object containing UTF-8 encoded text
> New in GJS 1.70 (GNOME 41)
The `TextEncoder.encode()` method takes a string as input, and returns a
`Uint8Array` containing the text given in parameters encoded with the specific
method for that `TextEncoder` object.
### TextEncoder.encodeInto(input, output)
Parameters:
* input (`String`) — A string containing the text to encode
* output (`Uint8Array`) — A `Uint8Array` object instance to place the resulting
UTF-8 encoded text into.
Returns:
* (`{String: Number}`) — An object containing the number of UTF-16 units read
and bytes written
> New in GJS 1.70 (GNOME 41)
The `TextEncoder.encode()` method takes a string as input, and returns a
`Uint8Array` containing the text given in parameters encoded with the specific
method for that `TextEncoder` object.
The returned object contains two members:
* `read`
The number of UTF-16 units of code from the source that has been converted
over to UTF-8. This may be less than `string.length` if `uint8Array` did not
have enough space.
* `written`
The number of bytes modified in the destination `Uint8Array`. The bytes
written are guaranteed to form complete UTF-8 byte sequences.
doc/Environment.md
View file @ 6709d722
## Environment
# Environment
GJS allows runtime configuration with a number of environment variables.
### General
## General
* `GJS_PATH`
......@@ -17,7 +17,7 @@ GJS allows runtime configuration with a number of environment variables.
Setting this variable to any value causes GJS to exit when an out-of-memory
condition is encountered, instead of just printing a warning.
### JavaScript Engine
## JavaScript Engine
* `JS_GC_ZEAL`
......@@ -31,7 +31,7 @@ GJS allows runtime configuration with a number of environment variables.
JavaScript engine.
### Debugging
## Debugging
* `GJS_DEBUG_HEAP_OUTPUT`
......@@ -75,7 +75,7 @@ GJS allows runtime configuration with a number of environment variables.
Set this variable to print a timestamp when logging.
### Testing
## Testing
* `GJS_COVERAGE_OUTPUT`
......
doc/Format.md 0 → 100644
View file @ 6709d722
# Format
The `Format` module is a mostly deprecated module that implements `printf()`
style formatting for GJS.
In most cases, native [template literals][template-literals] should be preferred
now, except in few situations like Gettext (See [Bug #60027][bug-60027]).
```js
const foo = 'Pi';
const bar = 1;
const baz = Math.PI;
// expected result: "Pi to 2 decimal points: 3.14"
// Native template literals
const str1 = `${foo} to ${bar*2} decimal points: ${baz.toFixed(bar*2)}`
// Format.vprintf()
const str2 = Format.vprintf('%s to %d decimal points: %.2f', [foo, bar*2, baz]);
```
#### Import
> Attention: This module is not available as an ECMAScript Module
The `Format` module is available on the global `imports` object:
```js
const Format = imports.format;
```
[template-literals]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals
[bug-60027]: https://savannah.gnu.org/bugs/?60027
### Format.format(...args)
> Deprecated: Use [`Format.vprintf()`](#format-vprintf) instead
Type:
* Prototype Function
Parameters:
* args (`Any`) — Formatting substitutions
Returns:
* (`String`) — A new formatted string
This function was intended to extend the `String` object and provide a
`String.format` API for string formatting.
Example usage:
```js
const Format = imports.format;
// Applying format() to the string prototype.
//
// This is highly discouraged, especially in GNOME Shell extensions where other
// extensions might overwrite it. Use Format.vprintf() directly instead.
String.prototype.format = Format.format;
// Usage with String.prototype.format()
// expected result: "A formatted string"
const str = 'A %s %s'.format('formatted', 'string');
```
### Format.printf(fmt, ...args)
> Deprecated: Use [template literals][template-literals] with `print()` instead
Type:
* Static
Parameters:
* fmt (`String`) — A format template
* args (`Any`) — Formatting substitutions
Substitute the specifiers in `fmt` with `args` and print the result to `stdout`.
Example usage:
```js
// expected output: A formatted string
Format.printf('A %s %s', 'formatted', 'string');
```
### Format.vprintf(fmt, args)
> Deprecated: Prefer [template literals][template-literals] when possible
Type:
* Static
Parameters:
* fmt (`String`) — A format template
* args (`Array(Any)`) — Formatting substitutions
Returns:
* (`String`) — A new formatted string
Substitute the specifiers in `fmt` with `args` and return a new string. It
supports the `%s`, `%d`, `%x` and `%f` specifiers.
For `%f` it also supports precisions like `vprintf('%.2f', [1.526])`. All
specifiers can be prefixed with a minimum field width (e.g.
`vprintf('%5s', ['foo'])`). Unless the width is prefixed with `'0'`, the
formatted string will be padded with spaces.
Example usage:
```js
// expected result: "A formatted string"
const str = Format.vprintf('A %s %s', ['formatted', 'string']);
// Usage with Gettext
Format.vprintf(_('%d:%d'), [11, 59]);
Format.vprintf(
Gettext.ngettext('I have %d apple', 'I have %d apples', num), [num]);
```
[template-literals]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals
doc/Gettext.md 0 → 100644
View file @ 6709d722
# Gettext
> See also: [`examples/gettext.js`][examples-gettext] for usage examples
This module provides a convenience layer for the "gettext" family of functions,
relying on GLib for the actual implementation.
Example usage:
```js
const Gettext = imports.gettext;
Gettext.textdomain('myapp');
Gettext.bindtextdomain('myapp', '/usr/share/locale');
let translated = Gettext.gettext('Hello world!');
```
#### Import
When using ESModules:
```js
import Gettext from 'gettext';
```
When using legacy imports:
```js
const Gettext = imports.gettext;
```
[examples-gettext]: https://gitlab.gnome.org/GNOME/gjs/blob/HEAD/examples/gettext.js
### Gettext.LocaleCategory
An enumeration of locale categories supported by GJS.
* `CTYPE = 0` — Character classification
* `NUMERIC = 1` — Formatting of nonmonetary numeric values
* `TIME = 2` — Formatting of date and time values
* `COLLATE = 3` — String collation
* `MONETARY = 4` — Formatting of monetary values
* `MESSAGES = 5` — Localizable natural-language messages
* `ALL = 6` — All of the locale
### Gettext.setlocale(category, locale)
> Note: It is rarely, if ever, necessary to call this function in GJS
Parameters:
* category (`Gettext.LocaleCategory`) — A locale category
* locale (`String`|`null`) — A locale string, or `null` to query the locale
Returns:
* (`String`|`null`) — A locale string, or `null` if `locale` is not `null`
Set or query the program's current locale.
Example usage:
```js
Gettext.setlocale(Gettext.LocaleCategory.MESSAGES, 'en_US.UTF-8');
```
### Gettext.textdomain(domainName)
Parameters:
* domainName (`String`) — A translation domain
Set the default domain to `domainName`, which is used in all future gettext
calls. Note that this does not affect functions that take an explicit
`domainName` argument, such as `Gettext.dgettext()`.
Typically this will be the project name or another unique identifier. For
example, GNOME Calculator might use something like `"gnome-calculator"` while a
GNOME Shell Extension might use its extension UUID.
### Gettext.bindtextdomain(domainName, dirName)
Parameters:
* domainName (`String`) — A translation domain
* dirName (`String`) — A directory path
Specify `dirName` as the directory that contains translations for `domainName`.
In most cases, `dirName` will be the system locale directory, such as
`/usr/share/locale`. GNOME Shell's `ExtensionUtils.initTranslations()` method,
on the other hand, will check an extension's directory for a `locale`
subdirectory before falling back to the system locale directory.
### Gettext.gettext(msgid)
> Note: This is equivalent to calling `Gettext.dgettext(null, msgid)`
Parameters:
* msgid (`String`) — A string to translate
Returns:
* (`String`) — A translated message
This function is a wrapper of `dgettext()` which does not translate the message
if the default domain as set with `Gettext.textdomain()` has no translations for
the current locale.
### Gettext.dgettext(domainName, msgid)
> Note: This is an alias for [`GLib.dgettext()`][gdgettext]
Parameters:
* domainName (`String`|`null`) — A translation domain
* msgid (`String`) — A string to translate
Returns:
* (`String`) — A translated message
This function is a wrapper of `dgettext()` which does not translate the message
if the default domain as set with `Gettext.textdomain()` has no translations for
the current locale.
[gdgettext]: https://gjs-docs.gnome.org/glib20/glib.dgettext
### Gettext.dcgettext(domainName, msgid, category)
> Note: This is an alias for [`GLib.dcgettext()`][gdcgettext]
Parameters:
* domainName (`String`|`null`) — A translation domain
* msgid (`String`) — A string to translate
* category (`Gettext.LocaleCategory`) — A locale category
Returns:
* (`String`) — A translated message
This is a variant of `Gettext.dgettext()` that allows specifying a locale
category.
[gdcgettext]: https://gjs-docs.gnome.org/glib20/glib.dcgettext
### Gettext.ngettext(msgid1, msgid2, n)
> Note: This is equivalent to calling
> `Gettext.dngettext(null, msgid1, msgid2, n)`
Parameters:
* msgid1 (`String`) — The singular form of the string to be translated
* msgid2 (`String`) — The plural form of the string to be translated
* n (`Number`) — The number determining the translation form to use
Returns:
* (`String`) — A translated message
Translate a string that may or may not be plural, like "I have 1 apple" and
"I have 2 apples".
In GJS, this should be used in conjunction with [`Format.vprintf()`][vprintf],
which supports the same substitutions as `printf()`:
```js
const numberOfApples = Math.round(Math.random() + 1);
const translated = Format.vprintf(Gettext.ngettext('I have %d apple',
'I have %d apples', numberOfApples), [numberOfApples]);
```
[vprintf]: https://gjs-docs.gnome.org/gjs/format.md#format-vprintf
### Gettext.dngettext(domainName, msgid1, msgid2, n)
> Note: This is an alias for [`GLib.dngettext()`][gdngettext]
Parameters:
* domainName (`String`|`null`) — A translation domain
* msgid1 (`String`) — A string to translate
* msgid2 (`String`) — A pluralized string to translate
* n (`Number`) — The number determining the translation form to use
Returns:
* (`String`) — A translated message
This function is a wrapper of `dngettext()` which does not translate the message
if the default domain as set with `textdomain()` has no translations for the
current locale.
[gdngettext]: https://gjs-docs.gnome.org/glib20/glib.dngettext
### Gettext.pgettext(context, msgid)
> Note: This is equivalent to calling `Gettext.dpgettext(null, context, msgid)`
Parameters:
* context (`String`|`null`) — A context to disambiguate `msgid`
* msgid (`String`) — A string to translate
Returns:
* (`String`) — A translated message
This is a variant of `Gettext.dgettext()` which supports a disambiguating
message context.
This is used to disambiguate a translation where the same word may be used
differently, depending on the situation. For example, in English "read" is the
same for both past and present tense, but may not be in other languages.
### Gettext.dpgettext(domainName, context, msgid)
> Note: This is an alias for [`GLib.dpgettext2()`][gdpgettext2]
Parameters:
* domainName (`String`|`null`) — A translation domain
* context (`String`|`null`) — A context to disambiguate `msgid`
* msgid (`String`) — A string to translate
Returns:
* (`String`) — A translated message
This is a variant of `Gettext.dgettext()` which supports a disambiguating
message context.
[gdpgettext2]: https://gjs-docs.gnome.org/glib20/glib.dpgettext2
### Gettext.domain(domainName)
> Note: This method is specific to GJS
Parameters:
* domainName (`String`) — A domain name
Returns:
* (`Object`) — An object with common gettext methods
Create an object with bindings for `Gettext.gettext()`, `Gettext.ngettext()`,
and `Gettext.pgettext()`, bound to a `domainName`.
doc/Hacking.md
View file @ 6709d722
......@@ -37,7 +37,7 @@ You can also skip this step if you are not writing any C++ code.)
## Dependencies
GJS requires five other libraries to be installed: GLib, libffi,
gobject-introspection, SpiderMonkey (also called "mozjs91" on some
gobject-introspection, SpiderMonkey (also called "mozjs102" on some
systems.) and the build tool Meson.
The readline library is not required, but strongly recommended.
We recommend installing your system's development packages for GLib,
......@@ -70,15 +70,15 @@ example, Fedora 36 or Ubuntu 22.04 and later versions), then you don't
need to build it yourself.
Install SpiderMonkey using your system's package manager instead:
<!--Ubuntu does not currently ship a build of libmozjs-91-->
<!--Ubuntu does not currently ship a build of libmozjs-102-->
<!-- <details>
<summary>Ubuntu</summary>
<code>sudo apt-get install libmozjs-91-dev</code>
<code>sudo apt-get install libmozjs-102-dev</code>
</details> -->
<details>
<summary>Fedora</summary>
<code>sudo dnf install mozjs91-devel</code>
<code>sudo dnf install mozjs102-devel</code>
</details>
If you _are_ writing C++ code, then please build SpiderMonkey yourself
......@@ -86,7 +86,7 @@ with the debugging features enabled.
This can save you time later when you submit your merge request, because
the code will be checked using the debugging features.
To build SpiderMonkey, follow the instructions on [this page](https://github.com/mozilla-spidermonkey/spidermonkey-embedding-examples/blob/esr91/docs/Building%20SpiderMonkey.md) to download the source code and build the library.
To build SpiderMonkey, follow the instructions on [this page](https://github.com/mozilla-spidermonkey/spidermonkey-embedding-examples/blob/esr102/docs/Building%20SpiderMonkey.md) to download the source code and build the library.
If you are using `-Dprefix` to build GJS into a different path, then
make sure to use the same build prefix for SpiderMonkey with `--prefix`.
......@@ -152,7 +152,7 @@ more likely to show up.
To see which GC zeal options are available:
```sh
JS_GC_ZEAL=-1 js91
JS_GC_ZEAL=-1 js102
```
We include three test setups, `extra_gc`, `pre_verify`, and
......@@ -216,7 +216,7 @@ This will build GJS into a separate build directory with code coverage
instrumentation enabled, run the test suite to collect the coverage
data, and open the generated HTML report.
[embedder](https://github.com/spidermonkey-embedders/spidermonkey-embedding-examples/blob/esr91/docs/Building%20SpiderMonkey.md)
[embedder](https://github.com/spidermonkey-embedders/spidermonkey-embedding-examples/blob/esr102/docs/Building%20SpiderMonkey.md)
## Troubleshooting
......
doc/Home.md
View file @ 6709d722
# GJS: Javascript Bindings for GNOME
The current stable series is built on Mozilla's SpiderMonkey 91,
featuring **ECMAScript 2022** and GObject Introspection making most of
the **GNOME platform API** available.
This page has moved to [`README.md`](README.md).
To find out when a language feature was implemented in GJS, review [NEWS][gjs-news] in the GitLab repository. In many cases older versions of GJS can be supported using [polyfills][mdn-polyfills] and [legacy-style GJS classes](Modules.md#lang).
GJS includes some built-in modules like Cairo and Gettext, as well as helpers for some core APIs like DBus and GVariants. See the [Modules](Modules.md) page for an overview of the built-in modules and their usage.
[gjs-news]: https://gitlab.gnome.org/GNOME/gjs/raw/HEAD/NEWS
[mdn-polyfills]: https://developer.mozilla.org/docs/Glossary/Polyfill
## GNOME API Documentation
There is official [GNOME API Documentation][gjs-docs] for GJS, including
everything from GLib and Gtk to Soup and WebKit2.
The [Mapping](Mapping.md) page has an overview of GNOME API usage in GJS such as subclassing, constants and flags, functions with multiple return values, and more.
There are also a growing number of [examples][gjs-examples] and thorough tests of language features in the [test suite][gjs-tests].
[gjs-docs]: https://gjs-docs.gnome.org/
[gjs-examples]: https://gitlab.gnome.org/GNOME/gjs/tree/HEAD/examples
[gjs-tests]: https://gitlab.gnome.org/GNOME/gjs/blob/HEAD/installed-tests/js
## Standalone Applications
It's possible to write standalone applications with GJS for the GNOME Desktop, and infrastructure for Gettext, GSettings and GResources via the `package` import. There is a package specification, template repository available and plans for an in depth tutorial.
* [GJS Package Specification](https://gitlab.gnome.org/GNOME/gjs/-/blob/HEAD/doc/Package/Specification.md)
* [GJS Package Template](https://github.com/gcampax/gtk-js-app)
GNOME Applications written in GJS:
* [GNOME Characters](https://gitlab.gnome.org/GNOME/gnome-characters)
* [GNOME Documents](https://gitlab.gnome.org/GNOME/gnome-documents)
* [GNOME Maps](https://gitlab.gnome.org/GNOME/gnome-maps)
* [GNOME Sound Recorder](https://gitlab.gnome.org/GNOME/gnome-sound-recorder)
* [GNOME Weather](https://gitlab.gnome.org/GNOME/gnome-weather)
* [GNOME Books](https://gitlab.gnome.org/GNOME/gnome-books)
* [Polari](https://gitlab.gnome.org/GNOME/polari) IRC Client
Third party applications written in GJS:
* [Tangram](https://github.com/sonnyp/Tangram)
* [Quick Lookup](https://github.com/johnfactotum/quick-lookup)
* [Foliate](https://github.com/johnfactotum/foliate)
* [Marker](https://github.com/fabiocolacio/Marker)
* [Gnomit](https://github.com/small-tech/gnomit)
* [Clapper](https://github.com/Rafostar/clapper/)
* [Flatseal](https://github.com/tchx84/Flatseal)
* [Almond](https://github.com/stanford-oval/almond-gnome/)
* [Commit](https://github.com/sonnyp/commit/)
* [Junction](https://github.com/sonnyp/Junction)
* [Oh My SVG](https://github.com/sonnyp/OhMySVG)
## Getting Help
* Discourse: https://discourse.gnome.org/
* Chat: https://matrix.to/#/#javascript:gnome.org
* Issue/Bug Tracker: https://gitlab.gnome.org/GNOME/gjs/issues
* StackOverflow: https://stackoverflow.com/questions/tagged/gjs
## External Links
* [GObjectIntrospection](https://wiki.gnome.org/action/show/Projects/GObjectIntrospection)
* [GNOME Developer Platform Demo](https://developer-old.gnome.org/gnome-devel-demos/stable/js.html) (Some older examples that still might be informative)
* [GNOME Shell Extensions](https://gjs.guide/extensions)
doc/Lang.md 0 → 100644
View file @ 6709d722
# Lang
The `Lang` module is a collection of deprecated features that have been
completely superseded by standard ECMAScript. It remains a part of GJS for
backwards-compatibility reasons, but should never be used in new code.
#### Import
> Attention: This module is not available as an ECMAScript Module
The `Lang` module is available on the global `imports` object:
```js
const Lang = imports.lang
```
### Lang.bind(thisArg, function, ...args)
> Deprecated: Use [`Function.prototype.bind()`][function-bind] instead
Type:
* Static
Parameters:
* thisArg (`Object`) — A JavaScript object
* callback (`Function`) — A function reference
* args (`Any`) — A function reference
Returns:
* (`Function`) — A new `Function` instance, bound to `thisArg`
Binds a function to a scope.
[function-bind]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Function/bind
### Lang.Class(object)
> Deprecated: Use native [JavaScript Classes][js-class] instead
Type:
* Static
Parameters:
* object (`Object`) — A JavaScript object
Returns:
* (`Object`) — A JavaScript class expression
...
Example usage:
```js
const MyLegacyClass = new Lang.Class({
_init: function() {
let fnorb = new FnorbLib.Fnorb();
fnorb.connect('frobate', Lang.bind(this, this._onFnorbFrobate));
},
_onFnorbFrobate: function(fnorb) {
this._updateFnorb();
}
});
```
[js-class]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Classes
### Lang.copyProperties(source, dest)
> Deprecated: Use [`Object.assign()`][object-assign] instead
Type:
* Static
Parameters:
* source (`Object`) — The source object
* dest (`Object`) — The target object
Copy all properties from `source` to `dest`, including those that are prefixed
with an underscore (e.g. `_privateFunc()`).
[object-assign]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/assign
### Lang.copyPublicProperties(source, dest)
> Deprecated: Use [`Object.assign()`][object-assign] instead
Type:
* Static
Parameters:
* source (`Object`) — The source object
* dest (`Object`) — The target object
Copy all public properties from `source` to `dest`, excluding those that are
prefixed with an underscore (e.g. `_privateFunc()`).
[object-assign]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/assign
### Lang.countProperties(object)
> Deprecated: Use [`Object.assign()`][object-assign] instead
Type:
* Static
Parameters:
* object (`Object`) — A JavaScript object
[object-assign]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/assign
### Lang.getMetaClass(object)
Type:
* Static
Parameters:
* object (`Object`) — A JavaScript object
Returns:
* (`Object`|`null`) — A `Lang.Class` meta object
...
### Lang.Interface(object)
> Deprecated: Use native [JavaScript Classes][js-class] instead
Type:
* Static
Parameters:
* object (`Object`) — A JavaScript object
Returns:
* (`Object`) — A JavaScript class expression
...
[js-class]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Classes