diff --git a/packages/generator-typescript/templates/gjs/ambient.d.ts b/packages/generator-typescript/templates/gjs/ambient.d.ts index 2132d4a0b..c2b71d36c 100644 --- a/packages/generator-typescript/templates/gjs/ambient.d.ts +++ b/packages/generator-typescript/templates/gjs/ambient.d.ts @@ -31,7 +31,7 @@ declare module 'system' { import System from '@girs/gjs/system'; export default System; <%_ } else { _%> - const System: typeof import('./gettext.js').default; + const System: typeof import('./system.js').default; export default System; export const programInvocationName: typeof import('./system.js').programInvocationName; diff --git a/packages/generator-typescript/templates/gjs/system.d.ts b/packages/generator-typescript/templates/gjs/system.d.ts index 55c82aed2..350227a56 100644 --- a/packages/generator-typescript/templates/gjs/system.d.ts +++ b/packages/generator-typescript/templates/gjs/system.d.ts @@ -1,32 +1,175 @@ <%_ const GObject = dep.find('GObject') _%> <%- GObject ? GObject.importDef : '' %> +/** + * This property contains the name of the script as it was invoked from the command + * line. In C and other languages, this information is contained in the first element of + * the platform's equivalent of argv, but GJS's ARGV only contains the + * subsequent command-line arguments. In other words, `ARGV[0]` in GJS is the same as `argv[1]` in C. + * @version Gjs 1.68 + */ export const programInvocationName: string + +/** + * This property contains version information about GJS. + */ export const version: number + +/** + * The full path of the executed program. + * @version Gjs 1.68 + */ export const programPath: string | null -/** Equal to ARGV */ + +/** + * A list of arguments passed to the current process. + * This is effectively an alias for the global `ARGV`, which is misleading in that + * it is not equivalent to the platform'`s` argv. + * @version Gjs 1.68 + */ export const programArgs: string[] -export function exit(code: number): void -export function addressOfGObject(o: GObject.Object): object -export function addressOf(o: any): object + +/** + * Return the memory address of any object as a string. + * This is the address of memory being managed by the JavaScript engine, which may + * represent a wrapper around memory elsewhere. + * **Caution**, don't use this as a unique identifier! + * JavaScript's garbage collector can move objects around in memory, or + * deduplicate identical objects, so this value may change during the execution + * of a program. + * @param o Any Object + * @returns A hexadecimal string (e.g. `0xb4f170f0`) + */ +export function addressOf(o: any): string + +/** + * Return the memory address of any GObject as a string. + * See also {@link addressOf} + * @param o Any {@link GObject.Object}-derived instance + * @returns A hexadecimal string (e.g. `0xb4f170f0`) + * @version Gjs 1.58 + */ +export function addressOfGObject(o: GObject.Object): string + +/** + * Inserts a breakpoint instruction into the code. + * **Warning**: Using this function in code run outside of GDB will abort the process. + * With `System.breakpoint()` calls in your code, a GJS program can be debugged by + * running it in GDB: + * ```bash + * gdb --args gjs script.js + * ``` + * Once GDB has started, you can start the program with run. When the debugger + * hits a breakpoint it will pause execution of the process and return to the + * prompt. You can then use the standard `backtrace` command to print a C++ stack + * trace, or use `call gjs_dumpstack()` to print a JavaScript stack trace: + * ```bash + * (gdb) run + * tarting program: /usr/bin/gjs -m script.js + * ... + * Thread 1 "gjs" received signal SIGTRAP, Trace/breakpoint trap. + * (gdb) call gjs_dumpstack() + * == Stack trace for context 0x5555555b7180 == + * #0 555555640548 i file:///path/to/script.js:4 (394b8c3cc060 @ 12) + * #1 5555556404c8 i file:///path/to/script.js:7 (394b8c3cc0b0 @ 6) + * #2 7fffffffd3a0 b self-hosted:2408 (394b8c3a9650 @ 753) + * #3 5555556403e8 i self-hosted:2355 (394b8c3a9600 @ 375) + * (gdb) + * ``` + * To continue executing the program, you can use the `continue` (or `cont`) to + * resume the process and debug further. + * Remember that if you run the program outside of GDB, it will abort at the + * breakpoint, so make sure to remove any calls to `System.breakpoint()` when + * you're done debugging. + */ +export function breakpoint(): void + +/** + * Clears the timezone cache. + * This is a workaround for SpiderMonkey Bug [#1004706](https://bugzilla.mozilla.org/show_bug.cgi?id=1004706). + */ +export function clearDateCaches(): void + /** Runs the garbage collector */ export function gc(): void + +/** + * Return the reference count of any GObject-derived type. When an object's + * reference count is zero, it is cleaned up and erased from memory. + * @param o A {@link GObject.Object} + */ export function refcount(o: GObject.Object): number -export function dumpHeap(path: string): void -export function dumpMemoryInfo(path: string): void +/** + * See also: The [heapgraph](https://gitlab.gnome.org/GNOME/gjs/blob/HEAD/tools/heapgraph.md) utility in the GJS repository. + * Dump a representation of internal heap memory. If `path` is not given, GJS will + * write the contents to `stdout`. + * @param path Optional file path + */ +export function dumpHeap(path?: string): void + +/** + * Dump internal garbage collector statistics. If `path` is not given, GJS will + * write the contents to `stdout`. + * @param path Optional file path + * @version Gjs 1.70 + * @example Output: + * ```json + * { + * "gcBytes": 794624, + * "gcMaxBytes": 4294967295, + * "mallocBytes": 224459, + * "gcIsHighFrequencyMode": true, + * "gcNumber": 1, + * "majorGCCount": 1, + * "minorGCCount": 1, + * "sliceCount": 1, + * "zone": { + * "gcBytes": 323584, + * "gcTriggerBytes": 42467328, + * "gcAllocTrigger": 36097228.8, + * "mallocBytes": 120432, + * "mallocTriggerBytes": 59768832, + * "gcNumber": 1 + * } + * } + * ``` + * + */ +export function dumpMemoryInfo(path?: string): void + +/** + * This works the same as C's exit() function; exits the program, passing a + * certain error code to the shell. The shell expects the error code to be zero if + * there was no error, or non-zero (any value you please) to indicate an error. + * + * This value is used by other tools such as `make`; if `make` calls a program that + * returns a non-zero error code, then `make` aborts the build. + * @param code An exit code + */ +export function exit(code: number): void +/** + * The System module provides common low-level facilities such as access to + * process arguments and exit(), as well as a number of useful functions and + * properties for debugging. + * + * Note that the majority of the functions and properties in this module should not + * be used in normal operation of a GJS application. + */ declare const System: { programInvocationName: typeof programInvocationName, version: typeof version, programPath: typeof programPath, programArgs: typeof programArgs, - exit: typeof exit, - addressOfGObject: typeof addressOfGObject, addressOf: typeof addressOf, + addressOfGObject: typeof addressOfGObject, + breakpoint: typeof breakpoint, + clearDateCaches: typeof clearDateCaches, gc: typeof gc, refcount: typeof refcount, dumpHeap: typeof dumpHeap, dumpMemoryInfo: typeof dumpMemoryInfo, + exit: typeof exit, } export default System \ No newline at end of file