Building

libmatoya changes frequently and is not intended to be distributed as a shared library. It will never use wrapped build systems like CMake, Visual Studio projects, or Automake. libmatoya ships with simple makefiles that output lean static libraries. The only public header you are required to include is matoya.h.

Windows

nmake

macOS / Linux

make

iOS / tvOS

# Device
make TARGET=iphoneos ARCH=arm64
make TARGET=appletvos ARCH=arm64

# Simulator
make TARGET=iphonesimulator
make TARGET=appletvsimulator

Web

make WASM=1

See Building for the Web.

Android

# Must be built on a Unix environment, see the GNUmakefile for details
make android

Dependencies

A major goal of libmatoya is to avoid third-party dependencies and wrap system dependencies wherever possible. This approach keeps libmatoya very small while relying on performant and well-tested libraries shipped with the target platforms. Required system libraries are guaranteed to be present per Platform Support. Third-party dependencies are compiled with libmatoya from the /deps directory.

Library	License	Role
WebView2	BSD	Microsoft WebView2 headers
OpenGL	MIT	OpenGL and OpenGLES headers
Vulkan	Apache 2.0	Vulkan headers

On Linux, you are required only to link against the C standard library. All other dependencies are optional and queried at run time with dlopen. Most of these "system" dependencies all have a long history of ABI stability and wide package manager support on the major distros.

Library	Purpose
libX11	Application / window creation
libXi	Relative mouse mode
libXcursor	PNG cursor handling
libXfixes	Improved copy / paste behavior
libGL	OpenGL support
libvulkan	Vulkan support
libcurl	HTTP / WebSocket
libjpeg	Image decoding
libpng16	Image decoding
libasound	Audio playback
libudev	Game controller support
libcrypto	AES-GCM, general cryptography
libssl	DTLS support
libsteam_api	Steam WebView

Building for the Web

The "Web" platform means building for a sandboxed, web browser environment that runs WebAssembly and JavaScript. Most C code can be compiled and run verbatim in WebAssembly, and the browser's JavaScript API can be thought of as a suite of system libraries.

Two JavaScript files are necessary when deploying your app: matoya.js and matoya-worker.js. Only matoya.js should be imported by your Web app, but matoya-worker.js will be used for spawning threads and must be located side-by-side to matoya.js.

libmatoya uses the WASI SDK for its WebAssembly build toolchain and C standard library support. When running make WASM=1, the makefile expects to find the WASI SDK located at $(HOME)/wasi-sdk.

Only two functions and one global variable are formally exported by matoya.js:

• MTY_Start(bin, container, userEnv)
• MTY_SignalPtr(sync)
• MTY_MEMORY

MTY_Start is called with the path to your compiled WebAssembly binary (bin), a DOM element to attach the application's <canvas> drawing surface (container), and an optional additional set of functions that are callable from the native code (userEnv, in the form {function_name: function, ...}). The functions imported via the userEnv argument are always called on the main JavaScript thread, and may need to use MTY_WaitPtr and MTY_SignalPtr to synchronize.

MTY_MEMORY points to the WebAssembly.Memory object used by bin. C pointers are nothing more than offsets into MTY_MEMORY.buffer, a large SharedArrayBuffer representing all of the addressable memory used by the program, including the heap and each thread's stack and thread local storage.

MTY_RunAndYield should be considered when targeting the Web. The main thread, and often times at least one additional thread, spend their time in long-lived while or for loops. A libmatoya app calls MTY_AppRun on the main thread, which blocks until the app is ready to exit. When targeting the Web, it is important to use MTY_RunAndYield on any additional threads that have long-lived loops.