====== Porting WonderWitch applications ======

WonderWitch applications compiled using the official Qute SDK require a copy of FreyaOS (and FreyaBIOS) to run. Unfortunately, nowadays a loose WonderWitch cartridge required to run such programs can go for as much as $100 on the second-hand market, with the full SDK fetching prices above $200 - much more than the console itself. This makes not just creating, but even running WonderWitch applications inaccessible to most hobbyists.

(If you're an employee of Qute Corporation reading this, I would be very happy to volunteer and help resolving this situation.)

However, there already exists a large base of tutorials and software, including open source software, written for the API provided by Freya. One way to facilitate interoperability between the Wonderful toolchain (and, by extension, alternate execution environments) and such WonderSwan software would be to reimplement the required parts of the Freya API. In the past, projects like //WSSim// and //WWWLib// have been created to achieve this, as well as dedicated emulators like //MiracleMage//.

The Wonderful toolchain provides the ''libwwcl'' (WWitch Compatibility Layer) library for this purpose - a clean room reimplementation of selected Freya APIs.

===== Creating a libwwcl project =====

To create a libwwcl project template, use the ''-t wwcl'' argument when creating a new project:

    $ wf-wswantool project new -t wwcl new_project_name

===== Porting notes =====

  * While a Freya application uses the Makefile to configure the default memory layout (ASCII1, ASCII2, JAPANESE1, JAPANESE2), libwwcl relies on ''WWCL_INIT_MODE'' macros and the ''wwcl_init()'' function for this.
    * These macros and functions are provided in ''<wwcl.h>'', which is a new header that can be used instead of ''<sys/bios.h>''.
    * The macros are entirely optional. If you want to declare the memory layout yourself using [[wswan:guide:memory_management|the Wonderful toolchain's]] memory management, that is supported - use ''wwcl_init_custom()'' in this situation.
  * A Freya application uses on-cartridge SRAM as static data space. This is not currently available on Wonderful - however, WonderSwan Color 
    * gcc-ia16 requires a ''__far'' modifier for all constant arrays to be stored in ROM. See [[wswan:guide:memory_management#addressing_ram_and_rom|Addressing RAM and ROM]] for more information.
  * The Text API operates on Shift-JIS strings. To make gcc-ia16 use Shift-JIS strings instead of UTF-8 strings, pass ''-fexec-charset=shift-jis'' to the compiler.

===== Implementation status =====

//The implementation is incomplete; you can help by [[https://github.com/WonderfulToolchain/target-wswan-syslibs/tree/main/libwwcl|expanding it]].// 

  * Bank (''bank.h'') is not implemented.
  * Color (''libwwc.h'') is mostly implemented.
  * Comm (''comm.h'') is mostly implemented (''comm_xmodem'' missing).
  * Display (''disp.h'') is fully implemented.
  * Key (''key.h'') is partially implemented (key repeat support missing).
  * Sound (''sound.h'') is mostly implemented.
  * System (''system.h'') is partially implemented (a lot of its functionality is only useful inside a FreyaOS environment, however).
  * Text (''text.h'') is partially implemented (cursor support missing).
  * Timer (''timer.h'') is partially implemented (real time clock support missing).