GopalOS Developer Manual
Intro
GopalOS is a web-based operating system with a JSON-based filesystem and programs such as a File Manager, Text Editor, search engine, and more!
GopalOS File System
Every filesystem entry in GopalOS is in the following format:
[filename]: {
type: filetype,
content: filecontent,
other: otherMetadata
}
It is required that content is defined using the syntax content: function() {} or content: () => {} and not the content() {} syntax. The filetype key has a string value containing the file extension in lowercase (e.g. "txt"). In GopalOS, there are three directories and one file on the root directory. The /version.var file contains a string representing the current version string of GopalOS. The other four directories are /home, /apps, /lib, and /system, which store user-made files, application files, library files, and system files, respectively. The /version.var file and the four aforementioned directories are the only items that should be in the root directory.
There are many file types, such as txt, js, pgm, html, css, and var. Most of these are self-explanatory. js files and pgm files both store JavaScript functions; the difference is that pgm files are expected to be run by the user (e.g. by clicking on it in the File Manager or running through Terminal), and JS files are expected to be run from other programs or JavaScript code. JS files take whatever arguments they need, whilePGM files should not only take a single argument - an object containing runtime information (including the working directory and command-line arguments).
A directory is a special file with filetype dir whose content property is a JSON object containing other files/directories. In UIs, directories should be treated conceptually as "folders" (as they are in File Manager).
Unlike some operating systems, the file's name (without the extension) is its unique key in the directory. It is not possible to have two different files with the same name but different file extensions (file types).
The GopalOS filesystem supports file/folder names with periods in them. This causes a potential ambiguity with a requested path - does /home/example.hello.world refer to a folder example.hello.world, or a file example.hello of type world? Due to this, there are separate functions for accessing files and folders from path strings. However, it is forbidden to have a file with extension and folder to have the same name in the same directory.
GopalOS Apps
An app's files are stored in the /apps directory, with a folder name equal to that of the app ID. For example, File Manager's app ID is "file-manager" and its files are located in /apps/file-manager. The files in a basic app's (i.e. with a load script and standard window) directory is as follows:
app-id.pgm: This is the program file, which runs the load script, displays the window, and optionally registers a taskbar icon (to enable minimizing or pinning the program). The file name of the launch program must be the app ID. For example, File Manager's app ID is "file-manager" and its launch program is located at /apps/file-manager/file-manager.pgm
load.js: This is the file that is usually run on program start. For example, in File Manager, it loads the list of files and displays them.
window.html: This is the file that contains the HTML markup code for the app's main window. The contents of this file will be inserted into the <div id="windows"> element by the load.js file.
install.js: This optional file contains code that will be run when the app is installed (e.g. from Package Installer).
uninstall.js: This optional file contains code that will be run when the app is uninstalled (e.g. from Application Manager).
An app can also store preferences or other configuration files in the /home/appdata folder. An app must store these files in the /appdata/app-id folder (where app-id is the app's ID). This must be used for user-set options or user-made data only, not for internal program code.
Information about all installed apps is stored in the variable os.apps. Each entry has the following structure:
[appID]: {
name: appName,
icon: appIcon,
desc: appDescription,
globalID: optionalAppGlobalID,
version: versionString
}
The app name, app description, and app version string are self-explanatory. The icon should be the same as what the app uses in its taskbar icon. The globalID key is optional; apps installed from the App Center have a global ID in the format Publisher.OptionalCategory.AppName.
GopalOS Processes
Processes are functions that run recurringly in the background. The newProcess() function is used to create a new process. The type of the process can be specified as a time interval or an animation frame interval. The syntax of the function is below (using TypeScript-like notation):
newProcess(
name: string
func: Function (this could also be a getRef() call to a js or pgm file)
group: string | null (default: null)
interval: number (default: 1000)
type: "setInterval" | "reqAnimFrame" (default: "setInterval")
): void
For example, this is the function call used to start the Taskbar Clock Updater process:
newProcess(
"Taskbar Clock Updater",
getRef("/system/tbar-clock-updt"),
"Taskbar Icon Updater",
10
);
The file /system/tbar-clock-updt.pgm populates the taskbar clock field with the current time, and it is run every 10 ms.