# 8bitworkshop IDE User Manual  ## Using the IDE To start the IDE, open https://8bitworkshop.com in your web browser and click **Continue to 8bitworkshop IDE**. For best results, use a recent version of Mozilla Firefox, Google Chrome, or Apple Safari. ### Choosing a Platform The 8bitworkshop IDE supports a number of different hardware platforms. You can switch between them using the pulldown to the right of the main menu.  ### Example Programs The IDE is packaged with several example programs for each platform. To the right of the menu icon, you can access a Project Selector drop-down menu that allows you to select a file to load.  You can edit these files as much as you want --- all changes are persisted in browser local storage and they'll be there if you close the browser tab and come back. If you want to restore one of the example files back to its original condition, select **File >> Revert to Original...** from the menu. To start from scratch, select **New Project...** from the menu. Type in the name of your new file, typically with a `.c` extension for C source files. You can also write 6502 assembler with the `.asm` extension. Each platform has its own virtual file system in the browser, so any edits or new files will only be visible to the current platform. ### Emulators The IDE includes built-in emulators for all platforms, which run your code on simulated hardware. To control the game, first click the emulator screen to gain focus. The IDE will show the keyboard commands used by the current platform. Some platforms also support gamepads. ### Compilers The IDE also includes C compilers and assemblers for most platforms. They run in the web browser, along with a web-based text editor. Each time you make a change to the code, it's immediately compiled. Any errors are displayed in a list in the upper-right corner of the page. To the left of each error is a link which you can click to go to the corresponding source code. If there are no errors, the emulator is restarted with the new ROM image, allowing you to see code changes near-instantly. ### Debugger The IDE includes a simple debugger which allows you to step through machine code instructions, view memory, and start and stop the program. The buttons at the top of the screen perform several debugging functions:  - **Reset:** Hard reset the emulator, then single-step to the first instruction. - **Pause:** Stop the emulator. - **Run:** Resume the emulator after pausing. - **Step:** Execute the next CPU instruction, then break. - **Next Frame/Interrupt:** Execute until the next video frame starts, then break. - **Run To Line:** Set a on the current line (the one the cursor is on). The emulator will stop when execution reaches that instruction. You can also click on the gutter to the left of the line. - **Step Out of Subroutine:** Run until the current subroutine returns, then break. - **Step Backwards:** Step back a single CPU instruction. These buttons may not be available on every platform: - **Analyze Timing:** This performs a *flow analysis* on your code, computing timing values for each instruction. - **Show Help:** Open a web page with more information on the selected platform. - **Start Recording:** Enable the replay feature, which lets you rewind the emulator, scrolling to arbitrary frames and CPU cycles. Whenever the IDE hits a breakpoint or is single-stepped, a debug window appears in the lower-right of the screen. This shows the internal state of the CPU, including all registers and flags. You can click the links at the bottom to see additional info.  ## Sidebar The sidebar to the left of the editor contains a list of all source files in your project. It will contain a link to the main file (the one that appears in the pulldown) and any included or linked files. If listing files are generated, they will also be available. Depending on the platform selected, there may be one or more additional tools available: ### Disassembly Disassembles the program at the current Program Counter. ### Memory Browser Displays a dump of all CPU memory. ### Memory Map Displays a handy memory map of the system. Certain tools (like linkers) will give additional segment info here. ### VRAM Browser Displays a dump of all Video RAM memory, for systems with a separate VDP. ### Debug Tree Shows a hierarchical view of system debug info. ### Memory Probe Shows a bitmap representing read/write activity across system memory. ### CRT Probe Like the Memory Probe, but follows the sweep of the electron beam (for raster displays). ### Probe Log Shows a textual log of CPU/memory activity. ### Symbol Profiler Shows a list of symbols, with read/write counts. ### Asset Editor Parses assets (like bitmaps and palettes) and allows editing. (TODO: more documentation) ## Managing Files You can export and import files, share playable links and videos, sync projects to GitHub, and pull projects from GitHub. ### Importing and Exporting Files If you plan to clear cookies or use different browsers or computers, you may need to export your work and import it. To save your files outside of browser cache: 1. Select **Download** from the menu. 2. Choose an option: - **Download Source File** prompts you to download the active source file. - **Download ROM Image** prompts you to download the compiled --- a file that contains the entire game and can be used in a standalone emulator. - **Download Project as Zip** prompts you to download the active project as a zip file. - **Download All Changes as Zip** prompts you to download all files included in the active platform. 3. When prompted, select a location on your computer and save the file. To import source files back into the browser: - From the menu, select **Upload**, navigate to the source file on your computer when prompted, and click **Open**. ### Sharing Projects You can share playable links and videos (seven second animated GIFs) with others. Playable links actually contain the project code inside the URL. This allows you to share your work without storing it remotely or worrying about the permanence of the URL. One caveat, however, is that some browsers may not support the URL length. To share a playable link: 1. From the menu, select **Share**. 2. Select **Share Playable Link...**. A pop-up appears with link options. 3. Select **Copy Direct Link** to copy the link to your clipboard or **Copy IFRAME Tag** to copy a link you can embed inside an IFRAME for publishing on a web page. 4. Click **Close** to exit the window. To share a seven second animated GIF: 1. From the menu, select **Share**. 2. Select **Record Video...**. You'll see the emulator window background turn red. When complete, a pop-up appears displaying a preview. 3. Right-click on the Preview and choose **Save Image As...** and save the animated GIF to your computer. 4. Click **Close** to exit the window. ### Syncing with GitHub You can now sync 8bitworkshop projects with GitHub source code repositories. From the 8bitworkshop IDE, you can import projects from GitHub repositories, publish your projects, and push/pull to/from GitHub repositories you have access to. When you publish or push your projects to GitHub, 8bitworkshop pushes your code and a compiled ROM file to your repository. To connect your GitHub account: 1. From the menu, select **Sync >> Sign in to Github...** 2. When prompted, enter your GitHub username and password. To import a project from a GitHub repository: 1. From the menu, select **Sync**, then choose **Import Project from Github...** 2. In the pop-up that appears, enter the URL of the repository you want to use (in the format `https://github.com/username/reponame`), then click **Import Project**. To close the project and access other projects and files: - Select **Leave Repository** from the Project Selector drop-down. To access the project later: - Select it from the **Repositories** section of the Project Selector drop-down. To remove a GitHub repository from local storage: - Select the repository you want to delete from the Project Selector drop-down. - From the menu, select **Sync >> Delete Local Repository**. - Type **YES** when prompted to confirm deletion from local storage, then select **OK**. To publish an 8bitworkshop project to a GitHub repository: 1. From the menu, select **Sync**, then choose **Publish Project on GitHub...** 2. When prompted, add a project name and description. The username will say "username", after you connect to GitHub, this will change to your GitHub account name. 3. Choose the visibility of the published project by choosing **Public** or **Private**. 4. Select a license type. 5. Click **Upload Project**. If you've already logged into GitHub, the project will upload to GitHub. If not, you'll be prompted to connect to GitHub and, after logging in, the project will upload. To push changes to a GitHub repository: 1. From the menu, select **Sync**, then choose **Push Changes to Repository...** 2. When prompted, enter a commit message and then select **Push Changes**. To pull changes from a GitHub repository: 1. From the menu, select **Sync**, then choose **Pull Latest from Repository**. 2. When prompted to pull from repository and replace all local files, select **OK**. Note that all local files will be overwritten; there is no merge capability via the browser. ### Projects With Multiple Files A project can support multiple files. All files included in the project must be referenced in the main project file, with one of these reference types: * Include File - A source file embedded in another source file using an `#include` or similar directive. * Linked File - A source file compiled/assembled and linked into the project alongside of the main file, using the `//#link` or `;#link` directive. A binary file can also be included into an assembly project using the `incbin` directive. * Resource File - If a file needs to be included in the project, but is not included or linked from the main project (e.g. it may be included from a non-main file) then use the `//#resource` or `;#resource` directive to add it. If a file cannot be found, check the syntax. Often double quotes are required, e.g. `#include "file.inc"`. Only system files that are part of the compiler toolchain can be found with the `` syntax. ### CC65 Custom Config Files CC65's linker is controlled with [configuration files](https://www.cc65.org/doc/ld65-5.html) that define memory areas and the layout of the final binary or ROM. You can tell the linker to use a custom config file in your main C program like so: ~~~c #define CFGFILE apple2-hgr2.cfg //#resource "apple2-hgr2.cfg" ~~~ Note the lack of quotes in the first line. ### File Extensions The extension (or suffix) of your source file determines the tool used to assemble or compile it. Here's a list of some common extensions: Extension | File Type | Tool -------------|-----------------|------------ `.c` | C source file | cc65, sdcc, cmoc `.s` `.ca65` | Assembler file | ca65 `.a` | Assembler file | dasm (vcs) `.nesasm` | Assember file | NESASM (nes) `.zmac` | Assember file | ZMAC (z80) `.v` | Verilog file | Verilator `.bb` `.bas` | batariBASIC file| batariBASIC (vcs) `.fb` `.bas` | FastBASIC file | FastBASIC (atari8)