The-Homebrew-Cloud/N64FlashcartMenu
2
0
Fork 0
mirror of https://github.com/Polprzewodnikowy/N64FlashcartMenu.git synced 2025-10-19 02:09:33 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
gh-pages
N64FlashcartMenu/md_docs_299__developer__guide.html
networkfusion 73f9d302e5 deploy: de1b8dac4b
2025-10-07 22:02:28 +00:00

204 lines
13 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.12.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>N64FlashcartMenu: 99_developer_guide</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname">N64FlashcartMenu
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.12.0 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() { codefold.init(0); });
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
initMenu('',true,false,'search.php','Search',false);
$(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function(){ initResizable(false); });
/* @license-end */
</script>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
</div><!-- top -->
<div id="doc-content">
<div><div class="header">
<div class="headertitle"><div class="title">99_developer_guide</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="el" href="md_docs_200__index.html">Return to the index</a> </p>
<h2><a class="anchor" id="autotoc_md110"></a>
Developer Guide</h2>
<dl class="section remark"><dt>Remarks</dt><dd>You should use the pre-configured dev container in VSCode to ensure easy development.</dd></dl>
<p>Expected pre-requsites:</p><ul>
<li><a href="https://docs.docker.com/engine/install/">Docker</a> or <a href="https://podman.io/docs/installation">Podman</a> container environment (for dev container support).</li>
<li><a href="https://code.visualstudio.com/download">VSCode</a>.</li>
</ul>
<h3><a class="anchor" id="autotoc_md111"></a>
A quick start video tutorial on how to set up your environment</h3>
<p><a href="http://www.youtube.com/watch?v=h05ufOsRgZU" title="Docker Devcontainer quick start guide"><img src="http://img.youtube.com/vi/h05ufOsRgZU/0.jpg" alt="Docker Devcontainer quick start guide" class="inline"/></a>.</p>
<h3><a class="anchor" id="autotoc_md112"></a>
How to debug</h3>
<p>Within the code, use the <code>debugf</code> command, and then deploy using a debug build e.g. <code>make run-debug</code>.</p>
<div class="fragment"><div class="line">debugf(<span class="stringliteral">&quot;joybus_rtc_detect_async: %s %s %s %s\n&quot;</span>,</div>
<div class="line"> detected ? <span class="stringliteral">&quot;detected&quot;</span> : <span class="stringliteral">&quot;not detected&quot;</span>,</div>
<div class="line"> status.stopped ? <span class="stringliteral">&quot;stopped&quot;</span> : <span class="stringliteral">&quot;running&quot;</span>,</div>
<div class="line"> status.crystal_bad ? <span class="stringliteral">&quot;crystal:BAD&quot;</span> : <span class="stringliteral">&quot;crystal:OK&quot;</span>,</div>
<div class="line"> status.battery_bad ? <span class="stringliteral">&quot;battery:BAD&quot;</span> : <span class="stringliteral">&quot;battery:OK&quot;</span></div>
<div class="line">);</div>
</div><!-- fragment --><p> The output will then be shown within the console.</p>
<p>For the future: <code>ms-vscode.makefile-tools</code> will hopefully help (installed automatically in dev container). <br />
NOTE: it does not yet work with <code>F5</code>: see <a href="https://devblogs.microsoft.com/cppblog/now-announcing-makefile-support-in-visual-studio-code/">this blog post</a>. <br />
</p>
<h3><a class="anchor" id="autotoc_md113"></a>
How to deploy and/or debug to the SC64</h3>
<p>Make sure that your firmware is compatible (currently v2.20.2+). See: <a href="https://github.com/Polprzewodnikowy/SummerCart64/blob/v2.20.2/docs/00_quick_startup_guide.md#firmware-backupupdate">here</a></p>
<p>You will need to download a copy of the <code>sc64deployer</code> from <a href="https://github.com/Polprzewodnikowy/SummerCart64/releases/download/v2.20.2/">here</a> or build your own depending on the scenario.</p>
<dl class="section remark"><dt>Remarks</dt><dd>Toggle the N64 POWER switch to load and run the ROM.</dd></dl>
<h4><a class="anchor" id="autotoc_md114"></a>
From within the devcontainer</h4>
<h5><a class="anchor" id="autotoc_md115"></a>
To the native OS</h5>
<p>It is not currently possible to directly communicate with USB devices from a devcontainer. BUT, you can use a proxy TCP/IP connection as a workaround. <br />
To set up a "proxy", open a terminal window on the native OS, then <code>cd ./tools/sc64</code> and then <code>./sc64deployer.exe server</code>. Keep this terminal window open.</p>
<p>Then, in the dev container, use <code>make run</code> or <code>make run-debug</code>.</p>
<h5><a class="anchor" id="autotoc_md116"></a>
To a remote LAN device</h5>
<p>If you want to Deploy and debug to a fully remote target (over your LAN) Make sure that the remote target device (i.e. the one with the carts USB connected) has the server running (similar as specified in To the native OS, but):</p>
<dl class="section remark"><dt>Remarks</dt><dd>Make sure you specify its accessible IP and port.</dd></dl>
<div class="fragment"><div class="line">./sc64deployer server [THE_LAN_IP_ADDRESS]:9064</div>
</div><!-- fragment --><p>The following commands can then be run from the docker environment terminal:</p>
<p>To upload and run the ROM (requires power toggle): </p><div class="fragment"><div class="line">REMOTE=[THE_LAN_IP_ADDRESS]:9064 make run</div>
</div><!-- fragment --><p>To debug the ROM (requires power toggle): </p><div class="fragment"><div class="line">REMOTE=[THE_LAN_IP_ADDRESS]:9064 make run-debug</div>
</div><!-- fragment --><p>To debug the ROM with upload and auto reboot: (note: the current debugging session menu may not be the same as the file uploaded. you need to <code>make all</code> first to ensure the latest menu is uploaded). </p><div class="fragment"><div class="line">REMOTE=[THE_LAN_IP_ADDRESS]:9064 make run-debug-upload</div>
</div><!-- fragment --><h4><a class="anchor" id="autotoc_md117"></a>
Directly From your host (Windows) OS</h4>
<ul>
<li>Download the deployer <a href="https://github.com/Polprzewodnikowy/SummerCart64/releases/download/v2.20.2/sc64-deployer-windows-v2.20.2.zip">here</a>.</li>
<li>Extract and place <code>sc64deployer.exe</code> in the <code>tools/sc64</code> directory.</li>
<li>Then use <code>make run</code> or <code>make run-debug</code> in the terminal.</li>
</ul>
<h4><a class="anchor" id="autotoc_md118"></a>
To an SD Card</h4>
<p>NOTE: A "release" version of the SC64 menu is called <code>sc64menu.n64</code> and can be generated by running <code>make all</code> or running <code>make sc64</code>. You can then copy the resulting <code>sc64menu.n64</code> file to your SD card.</p>
<h3><a class="anchor" id="autotoc_md119"></a>
How to deploy and/or debug to other flashcarts/emulators</h3>
<h4><a class="anchor" id="autotoc_md120"></a>
Ares Emulator</h4>
<p>For ease of development and debugging, the N64FlashcartMenu ROM can run in the <a href="https://ares-emu.net/">Ares emulator</a> (without most flashcart features).</p>
<ul>
<li>Ensure you have the Ares emulator on your computer.</li>
<li>Load the <code>N64FlashcartMenu.n64</code> ROM.</li>
</ul>
<h4><a class="anchor" id="autotoc_md121"></a>
Others</h4>
<ul>
<li>Add the required file to the correct folder on your SD card.</li>
</ul>
<h3><a class="anchor" id="autotoc_md122"></a>
How to add debug code</h3>
<p>Within the code, use the <code>debugf</code> command, and then deploy using a debug build e.g. <code>make run-debug</code>.</p>
<div class="fragment"><div class="line">debugf(<span class="stringliteral">&quot;joybus_rtc_detect_async: %s %s %s %s\n&quot;</span>,</div>
<div class="line"> detected ? <span class="stringliteral">&quot;detected&quot;</span> : <span class="stringliteral">&quot;not detected&quot;</span>,</div>
<div class="line"> status.stopped ? <span class="stringliteral">&quot;stopped&quot;</span> : <span class="stringliteral">&quot;running&quot;</span>,</div>
<div class="line"> status.crystal_bad ? <span class="stringliteral">&quot;crystal:BAD&quot;</span> : <span class="stringliteral">&quot;crystal:OK&quot;</span>,</div>
<div class="line"> status.battery_bad ? <span class="stringliteral">&quot;battery:BAD&quot;</span> : <span class="stringliteral">&quot;battery:OK&quot;</span></div>
<div class="line">);</div>
</div><!-- fragment --><p> The output will then be shown within the terminal.</p>
<h3><a class="anchor" id="autotoc_md123"></a>
Using feature flags</h3>
<p>To enable features that are not build by default, you can input flags as part of the build. i.e. the current notible flags are: </p><div class="fragment"><div class="line">FEATURE_AUTOLOAD_ROM_ENABLED</div>
<div class="line">FEATURE_PATCHER_GUI_ENABLED</div>
<div class="line">BETA_SETTINGS</div>
<div class="line">FEATURE_DEPRECATED_FUNCTIONALITY</div>
</div><!-- fragment --><p> An example build command would be: <code>make clean &amp;&amp; FLAGS="-DFEATURE_PATCHER_GUI_ENABLED -DFEATURE_DEPRECATED_FUNCTIONALITY" make all</code></p>
<h3><a class="anchor" id="autotoc_md124"></a>
Update submodules</h3>
<p>To update to the latest version, use <code>git submodule update --remote</code> from the terminal.</p>
<h4><a class="anchor" id="autotoc_md125"></a>
libdragon</h4>
<p>This repo currently uses the <code>preview</code> branch as a submodule at a specific commit.</p><ul>
<li>To ensure your local instance is building against it, use <code>cd ./libdragon &amp;&amp; make clobber -j &amp;&amp; make libdragon tools -j &amp;&amp; make install tools-install -j &amp;&amp; cd ..</code></li>
</ul>
<h3><a class="anchor" id="autotoc_md126"></a>
Generate documentation</h3>
<p>Run <code>doxygen</code> from the dev container terminal. Make sure you fix the warnings before creating a PR! <br />
Generated documentation is located in the <code>output/docs</code> folder and auto-published to the <code>gh-pages</code> branch when merged with <code>main</code>.</p>
<p>Once merged, they can be viewed <a href="https://polprzewodnikowy.github.io/N64FlashcartMenu/">here</a>.</p>
<h4><a class="anchor" id="autotoc_md127"></a>
Test generated docs in the dev-container</h4>
<p>Testing the documentation locally allows you to preview changes and ensure everything renders correctly before submitting your changes.</p>
<p>Install Prerequisites: </p><div class="fragment"><div class="line">apt-get install ruby-full build-essential zlib1g-dev</div>
<div class="line">gem install jekyll bundler</div>
</div><!-- fragment --><p>You can then serve the webpage: </p><div class="fragment"><div class="line">cd output/docs &amp;&amp; jekyll serve</div>
</div><!-- fragment --> </div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Tue Oct 7 2025 22:02:27 for N64FlashcartMenu by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.12.0
</small></address>
</div><!-- doc-content -->
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink