Difference between revisions of "Nintendo 3DS"

From ScummVM :: Wiki
Jump to navigation Jump to search
(Removed duplicate information and added a link to the new docs. Added a “Developer information” section and moved the “Compiling ScummVM” section here.)
 
(5 intermediate revisions by 2 users not shown)
Line 13: Line 13:
buildbot=yes|
buildbot=yes|
firstversion=2.1.1|
firstversion=2.1.1|
maintainer=[[User:BgK|bgK]]|
maintainer=[[User:phcoder|phcoder]]|
packager=[[User:BgK|bgK]]|
packager=[[User:phcoder|phcoder]]|
pkgend=-3ds.zip|
pkgend=-3ds.zip|
icon=3ds|
icon=3ds|
Line 52: Line 52:


=== Compiling ScummVM  ===
=== Compiling ScummVM  ===
==== Prerequisites ====
Instructions on how to compile ScummVM for the 3DS can be found [[Compiling ScummVM/Nintendo 3DS|here]].
* Latest version of devkitPro, which comes with devkitARM and <code>libctru</code>
* <code>citro3d</code> thorugh devkitPro's pacman
* Optional: You should compile third-party libraries for the 3ds (commonly referred to as portlibs in the devkitPRO community). Some games requires these to operate properly.


==== Compiling third-party libraries ====
=== Debugging ScummVM ===
It is strongly recommended that you use devkitPro's pacman in order to get the most recent
portlibs for your build.


The following libraries can be downloaded with pacman:
''This section is based on information from [https://bugs.scummvm.org/ticket/11292#comment:4 Trac #11292].''


{|class="wikitable"
When reporting crashes to the issue tracker, it is recommended that you capture a backtrace of the crash? It's a bit of a convoluted process but it's not possible to do much without it. It's described here if you are not familiar:
!  Library      ||  Package             
|-
|  zlib        ||  3ds-zlib           
|-
|  libpng      ||  3ds-libpng         
|-
|  libjpeg      ||  3ds-libjpeg-turbo   
|-
|  freetype2    ||  3ds-freetype       
|-
|  libmad      ||  3ds-libmad         
|-
|  libogg      ||  3ds-libogg         
|-
|  tremor      ||  3ds-libvorbisidec   
|-
|  flac        ||  3ds-flac           
|-
|  curl        ||  3ds-curl           
|}


At the moment of writing, the version of <code>freetype2</code> packaged by devkitPro has an issue
* Create a build of ScummVM using "./configure --host=3ds --disable-all-engines --enable-engines=scumm_7_8,he,sci32 --enable-all-engines --enable-debug"
where it allocates too much data on the stack when ScummVM loads GUI themes.
* Get devkitARM from here: ​https://devkitpro.org/wiki/Getting_Started. You don't need to get the whole thing working, just the GDB debugger.
As a workaround, an older version can be used. Version 2.6.5 is known to work well. The
* Start ScummVM on your 3DS, go to the Rosalina menu (L+Down+Select), enable the debugger (Debugger options > enable debugger), go to the process list and select ScummVM (3dsx_app if you used the homebrew launcher). Take note of the IP address of your 3DS and the debugger port. They are displayed in the menu. For example, it might look like 192.168.1.87:4000. Close the Rosalina menu. If it closes ScummVM, try again, but open a dialog in ScummVM before opening the Rosalina menu (The keypress to close Rosalina is sometimes passed to ScummVM).
instructions below can be used to compile it.
* On your computer in the devkitARM shell, run "arm-none-eabi-gdb /path/to/scummvm.elf" (with the location where you downloaded that file). Then, in GDB, enter "target remote 192.168.1.87:4000" (with your IP and port) to connect to the 3DS. Enter 'c' to resume execution.
* On the 3DS, reproduce the crash.
* On the computer, GDB should have trapped the error. Enter "thread apply all bt" to print a backtrace.


At the moment of writing, <code>faad</code> is not in the devkitPro 3DS pacman repository. It
Please copy the backtrace into the ticket as well as other warnings or messages you may see in the debugger output.
can be compiled by following the instructions in the section below, in case it cannot
be found through pacman.


The following pacman packages are also recommended:
In case you don't succeed in capturing a backtrace, please attach the crash dump from the Luma error screen (they are saved on the SD card in /luma/dumps).
* <code>3ds-dev</code>
* <code>devkitpro-pkgbuild-helpers</code>


Once you have the <code>devkitpro-pkgbuild-helpers</code> package, you should be able to find
It's also recommended that you attach a copy of the log file, which can be found at "sdmc:/3ds/scummvm/scummvm.log".
the following scripts in your <code>/opt/devkitpro</code> folder:
* <code>devkitarm.sh</code>
* <code>3dsvars.sh</code>
 
Run them one after the other with `source` in order to setup your environment variables
for cross-compiling:
<syntaxhighlight lang="bash">
source /opt/devkitpro/devkitarm.sh
source /opt/devkitpro/3dsvars.sh
</syntaxhighlight>
 
After that, you can download the libraries you want to cross compile, run any autoconf
scripts that they may have, and then they can usually be built with the following steps
from their source directory:
 
<syntaxhighlight lang="bash">
mkdir -p $PORTLIBS_PREFIX
./configure --prefix=$PORTLIBS_PREFIX --host=arm-none-eabi --disable-shared --enable-static
make
make install
</syntaxhighlight>
 
Most libraries used can be compiled with same commands and configuration flags.
 
==== Manually setting up the environment ====
In case you don't have the helpers package downloaded, you can use the following to set-up
your environment variables.
 
It is assumed that you have these variables already set up. If not, then do so:
{|class="wikitable"
|  DEVKITPRO    ||  Your root devkitPro directory
|-
|  DEVKITARM    ||  Your root devkitARM directory (probably same as $DEVKITPRO/devkitARM)
|-
|  CTRULIB      ||  Your root libctru directory (probably same as $DEVKITPRO/libctru)
|}
 
In the source directory of the library:
<syntaxhighlight lang="bash">
export PORTLIBS_PREFIX=$DEVKITPRO/portlibs/3ds
export PATH=$DEVKITARM/bin:$PATH
export PKG_CONFIG_PATH=$PORTLIBS_PREFIX/lib/pkgconfig
export PKG_CONFIG_LIBDIR=$PORTLIBS_PREFIX/lib/pkgconfig
export CFLAGS="-g -march=armv6k -mtune=mpcore -mfloat-abi=hard -O2
                    -mword-relocations -ffunction-sections -fdata-sections"
export CPPFLAGS="-I$PORTLIBS_PREFIX/include -I$CTRULIB/include"
export LDFLAGS="-L$PORTLIBS_PREFIX/lib"
</syntaxhighlight>
 
==== Compiling ScummVM ====
Do the following in a fresh terminal.
 
In case you get a "compiler not found" message, add the toolchain's executables to your PATH:
<syntaxhighlight lang="bash">
export PATH=$DEVKITARM/bin:$PATH
</syntaxhighlight>
 
In case you get an error about "namespace _3DS", edit the line in /opt/devkitpro/3dsvars.sh that reads
<syntaxhighlight lang="bash">
export CPPFLAGS="-D_3DS -I${PORTLIBS_PREFIX}/include -I${DEVKITPRO}/libctru/include"
</syntaxhighlight>
and remove the "-D_3DS" part so that it reads
<syntaxhighlight lang="bash">
export CPPFLAGS="-I${PORTLIBS_PREFIX}/include -I${DEVKITPRO}/libctru/include"
</syntaxhighlight>
 
Note: In more recent codebases of ScummVM, you may or may not need to set the following beforehand:
<syntaxhighlight lang="bash">
export PKG_CONFIG_LIBDIR=$PORTLIBS_PREFIX/lib/pkgconfig
</syntaxhighlight>
See above for <code>$PORTLIBS_PREFIX</code>.
 
ScummVM doesn't provide the CA certificates bundle required by the cloud synchronization features.
You need to download it from the curl website: https://curl.haxx.se/ca/cacert.pem, and instruct
the build system to package it in the binary:
<syntaxhighlight lang="bash">
export DIST_3DS_EXTRA_FILES=/path/to/cacert.pem
</syntaxhighlight>
The name of the file must be <code>cacert.pem</code>.
 
From the root of the scummvm repository:
<syntaxhighlight lang="bash">
./configure --host=3ds --enable-plugins --default-dynamic
make
</syntaxhighlight>
 
Additionally compile to specific formats to be used on the 3DS:
<syntaxhighlight lang="bash">
make scummvm.3dsx
make scummvm.cia
</syntaxhighlight>
 
Assuming everything was successful, you'll be able to find the binary
files in the root of your scummvm folder.
 
Note: for the CIA format, you will need the <code>makerom</code> and <code>bannertool</code> tools which are
not supplied with devkitPro.
 
Note: using dynamic plugins as suggested is required when building with most or all of the
game engines enabled in order to keep the memory usage low and avoid stability issues.

Latest revision as of 21:56, 23 April 2024

3ds.png Nintendo 3DS Port
Latest Released Version 2.8.1
Supported Audio Options MP3, OGG, FLAC, Uncompressed
Additional Webpage(s) None
Maintainer(s) phcoder
Packager(s) phcoder
Forum Port Forum
Status Maintained
First Official Version 2.1.1

About

ScummVM has been ported to the Nintendo 3DS.

For more information, including how to install and use ScummVM, see the Nintendo 3DS user documentation.

Developer information

Compiling ScummVM

Instructions on how to compile ScummVM for the 3DS can be found here.

Debugging ScummVM

This section is based on information from Trac #11292.

When reporting crashes to the issue tracker, it is recommended that you capture a backtrace of the crash? It's a bit of a convoluted process but it's not possible to do much without it. It's described here if you are not familiar:

  • Create a build of ScummVM using "./configure --host=3ds --disable-all-engines --enable-engines=scumm_7_8,he,sci32 --enable-all-engines --enable-debug"
  • Get devkitARM from here: ​https://devkitpro.org/wiki/Getting_Started. You don't need to get the whole thing working, just the GDB debugger.
  • Start ScummVM on your 3DS, go to the Rosalina menu (L+Down+Select), enable the debugger (Debugger options > enable debugger), go to the process list and select ScummVM (3dsx_app if you used the homebrew launcher). Take note of the IP address of your 3DS and the debugger port. They are displayed in the menu. For example, it might look like 192.168.1.87:4000. Close the Rosalina menu. If it closes ScummVM, try again, but open a dialog in ScummVM before opening the Rosalina menu (The keypress to close Rosalina is sometimes passed to ScummVM).
  • On your computer in the devkitARM shell, run "arm-none-eabi-gdb /path/to/scummvm.elf" (with the location where you downloaded that file). Then, in GDB, enter "target remote 192.168.1.87:4000" (with your IP and port) to connect to the 3DS. Enter 'c' to resume execution.
  • On the 3DS, reproduce the crash.
  • On the computer, GDB should have trapped the error. Enter "thread apply all bt" to print a backtrace.

Please copy the backtrace into the ticket as well as other warnings or messages you may see in the debugger output.

In case you don't succeed in capturing a backtrace, please attach the crash dump from the Luma error screen (they are saved on the SD card in /luma/dumps).

It's also recommended that you attach a copy of the log file, which can be found at "sdmc:/3ds/scummvm/scummvm.log".