Differences

This shows you the differences between two versions of the page.

--- wswan:guide:porting_wwitch [2024/03/16 17:24] – asie
+++ wswan:guide:porting_wwitch [2024/03/17 07:21] (current) – asie
@@ Line 1: / Line 1: @@
 ====== 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 costing $100+ on the second-hand market, with the full SDK fetching prices above $200.
+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. Other projects like //WSSim// and //WWWLib// have been developed in the past to achieve this, while the Wonderful toolchain provides the ''libwwcl'' (WWitch Compatibility Layer) library for this purpose.
+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 =====
@@ Line 16: / Line 20: @@
     * 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.
-  * gcc-ia16 requires a ''__far'' modifier for all constant arrays stores in ROM. See [[wswan:guide:memory_management#addressing_ram_and_rom|Addressing RAM and ROM]] for more information.
+  * 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 following headers should be fully implemented:
+//The implementation is incomplete; you can help by [[https://github.com/WonderfulToolchain/target-wswan-syslibs/tree/main/libwwcl|expanding it]].//
-    * Display (''disp.h'')
-    * Color (''libwwc.h'')
-    * Sound (''sound.h'')
   * Bank (''bank.h'') is not implemented.
-  * Comm (''comm.h'') implements everything except ''comm_xmodem''.
+  * Color (''libwwc.h'') is mostly implemented.
-  * Key (''key.h'') is missing key repeat support.
+  * Comm (''comm.h'') is mostly implemented (''comm_xmodem'' missing).
-  * Text (''text.h'') is not implemented.
+  * Display (''disp.h'') is fully implemented.
-  * Timer (''timer.h'') is missing RTC (real time clock) support.
+  * Key (''key.h'') is partially implemented (key repeat support missing).
-  * The implementation of System (''system.h'') is very limited. However, many of its functions are not useful when not running on top of Freya.
+  * 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).