{"id":24177650,"url":"https://github.com/rosietheghostie/seaside","last_synced_at":"2026-05-19T05:38:57.262Z","repository":{"id":268035713,"uuid":"903171484","full_name":"RosieTheGhostie/seaside","owner":"RosieTheGhostie","description":"A modern tool to learn MIPS Assembly","archived":false,"fork":false,"pushed_at":"2025-02-27T16:39:50.000Z","size":798,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-02T17:12:23.303Z","etag":null,"topics":["assembler","assembly","interpreter","mips","tool"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RosieTheGhostie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-13T23:01:36.000Z","updated_at":"2025-01-31T01:47:25.000Z","dependencies_parsed_at":"2025-01-11T22:28:01.816Z","dependency_job_id":"b0915968-34ee-4f92-b413-7f82c9c0d800","html_url":"https://github.com/RosieTheGhostie/seaside","commit_stats":null,"previous_names":["rosietheghostie/seaside-v2","rosietheghostie/seaside"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RosieTheGhostie%2Fseaside","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RosieTheGhostie%2Fseaside/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RosieTheGhostie%2Fseaside/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RosieTheGhostie%2Fseaside/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RosieTheGhostie","download_url":"https://codeload.github.com/RosieTheGhostie/seaside/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241541451,"owners_count":19979121,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembler","assembly","interpreter","mips","tool"],"created_at":"2025-01-13T04:15:23.453Z","updated_at":"2025-10-26T09:47:20.480Z","avatar_url":"https://github.com/RosieTheGhostie.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"![seaside: a modern tool to learn MIPS assembly](res/banner.png)\n\n## Motivation\n\nAs of 2025, the gold standard for MIPS in education is [MARS](https://github.com/gon1332/mars). MARS is undoubtedly a wonderful piece of software, but it hasn't seen a major update in nearly a decade, and having a separate IDE for developing MIPS Assembly code is rather inconvenient.\n\nThe other major motivation for making seaside is that I, Rose Thorne, needed a Capstone project to graduate. I took a course on computer architecture during the Autumn 2024 semester, and seeing how my project needs to connect to a class I've taken, this seems like a good candidate.\n\n## Features\n\nseaside is currently a huge work-in-progress, so there aren't many features yet; however, I aim to make this as good (if not better) than MARS in the coming years.\n\n### Assembler (*partially implemented*)\n\nAssemble MIPS source code into raw binary files for execution.\n\n- [X] Single-file support\n- [ ] Multi-file support\n- [X] Basic instruction formats\n- [ ] Pseudo-instructions and extended formats\n- [ ] MARS-style macros\n- [ ] Support for `.set`\n- [ ] Support for `.eqv`\n\n### Interpreter (*mostly implemented*)\n\nRun programs seamlessly with the power of the seaside interpreter.\n\n- [X] 136/136 basic instructions supported by MARS\n- [ ] 27/39 system services supported by MARS\n  - [X] 8/8 printing services\n  - [X] 5/5 user input services\n  - [X] 4/4 file services\n  - [ ] 5/7 misc. system services\n  - [X] 5/5 RNG services\n  - [ ] 0/10 GUI services\n- [X] Control over user- and kernel-space\n\n### Disassembler\n\nConvert raw machine code into a human-readable representation using MIPS Assembly.\n\n- Single instruction disassembly\n- Full segment disassembly\n\n### Configuration (*mostly implemented*)\n\nChange the behavior of the seaside engine to your preference.\n\n- [X] Byte order (a.k.a. endianness)\n- [X] Memory map\n- [X] Allocated memory for each region\n- [X] Default values of registers\n- [X] Crash handler\n- [X] Current working directory for file IO\n- [X] Self-modifying code[^1]\n- [X] Delay slot[^1]\n- [X] System service mapping\n- [X] Ability to free heap allocations\n- [ ] + more!!!\n\n### [Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/) Compatibility (*not implemented*)\n\nUse with a complementary extension in your IDE to debug your programs.\n\n- [ ] Set breakpoints\n- [ ] Step through a program\n- [ ] Step over a procedure call\n- [ ] Inspect the contents of each register\n- [ ] View virtual memory in real-time\n\n## Usage\n\nWhen running a program, the seaside engine expects you to provide a directory with the following files:\n\n- 'text': MIPS machine code\n- 'extern' (optional): binary data\n- 'data' (optional): binary data\n- 'ktext' (optional): MIPS machine code\n- 'kdata' (optional): binary data\n\nEach of these files directly corresponds to their respective segments in the MIPS assembly code.\n\nAs of v1.2, seaside can assemble programs itself, so external tools like MARS are unnecessary; however, seaside's assembler is in its infancy and therefore lacks some features. If you want to use pseudo-instructions, macros, multiple source files, etc., MARS may be a better choice for the time being.\n\n## Installation\n\nWhen installing seaside, you have two options: run the installer, or compile from source.\n\n### Option A. Using the Installer (recommended)\n\nThe [seaside installer](https://github.com/RosieTheGhostie/seaside-installer) streamlines the process of installing, updating, and uninstalling seaside. It handles all the OS-dependent stuff for you, making for a much simpler and safer experience.\n\nStart by downloading the [latest release](https://github.com/RosieTheGhostie/seaside-installer/releases/latest) of the seaside installer. Newer versions of the installer don't necessarily allow you to install newer/older versions of seaside, but they may be less buggy and have more features.\n\nOnce the installer is on your system, navigate to the directory it's in via the terminal and run it. This should print the installer's usage. From this point, run whichever command best fits your needs.\n\n### Option B. Compiling from Source\n\nIf you wish to compile seaside yourself (for some reason), that is an option, too; however, it will require much more setup to get working.\n\n#### Prerequisites\n\nAs with any other Rust app, you'll need [cargo](https://doc.rust-lang.org/cargo/) to compile it. I won't go into detail on how to install that here, but you can find some information about it [here](https://doc.rust-lang.org/cargo/getting-started/installation.html).\n\nOther than that, seaside shouldn't need anything else to be installed on your computer.\n\n#### Compilation\n\n1. Navigate to seaside's root directory. This is the directory containing 'Cargo.toml'.\n2. In your terminal/command prompt of choice, enter the following command:\n    ```bash\n    cargo build -r\n    ```\n3. Sit back and watch the Rust compiler do its magic.\n\nAt this point, you should find the seaside executable in './target/release'. You may delete all other files in './target' if you wish, but leaving them around will speed up future compilations.\n\n#### Putting Stuff in the Right Directories\n\nFor the best experience, it is crucial to put files in the right place.\n\n##### 'Seaside.toml'\n\nseaside expects its global configuration file to be in a very specific location on your computer. This location is (like most other things going forward) OS-dependent.\n\n- **Linux:** /home/*user*/.config/seaside/Seaside.toml\n- **Windows:** C:\\\\Users\\\\*user*\\\\AppData\\\\Roaming\\\\seaside\\\\config\\\\Seaside.toml\n\nReplace *user* with your username.\n\nI recommend copying 'Seaside.toml' from the 'res' directory of this repository to the correct location for your machine.\n\n##### The seaside Executable\n\nWhile not technically required, having seaside in a specific location can expedite its use later on.\n\n- **Linux:** /usr/local/bin/seaside\n- **Windows:** C:\\\\ProgramData\\\\seaside\\\\seaside.exe\n\n\u003e [!NOTE]\n\u003e 'ProgramData' is a hidden folder on Windows.\n\nOn Linux, this step makes it possible to run seaside anywhere on your computer without referring to it by path. Windows, on the other hand, requires a bit more setup to achieve this.\n\n#### Adding seaside to 'Path' (Windows only)\n\nStart by pulling up the start menu (most easily done by pressing the \\[Win\\] key). Type in \"path\", which should bring up something that says \"Edit the system environment variables\". If so, open it and click the button that says \"Environment Variables\".\n\n\u003e [!TIP]\n\u003e If that didn't work for whatever reason, it's not too hard to go there yourself.\n\u003e\n\u003e 1. Open up Control Panel\n\u003e 2. In the search bar, type in \"environment\"\n\u003e 3. Under \"System\", click \"Edit environment variables for your account\"\n\nScrolling through the user variables, you should find one named \"Path\". This is a list of directories Windows will search whenever a command is executed. Double-click on it to open the editing interface.\n\n\u003e [!NOTE]\n\u003e This variable exists on Linux, too, but we didn't need to mess with it there because we used a directory that's already in the path.\n\nClick the \"New\" button and type in \"C:\\\\ProgramData\\\\seaside\". Once you press \\[Enter\\], click the \"OK\" buttons on both windows to commit your changes.\n\n### Configuration\n\nseaside has extensive configuration options, as described [above](#configuration-mostly-implemented). These are designed to mimic MARS' default settings out of the box, but you are welcome to change them however you see fit.\n\nIf seaside is ran in a directory with a file named 'Seaside.toml', that file will be used to set up the engine. Otherwise, it will use the global 'Seaside.toml'.\n\nExtensive documentation of the available configuration options can be found [here](https://github.com/RosieTheGhostie/seaside/wiki/Configuration-Manual).\n\n[^1]: The option exists in the config, but it doesn't do anything yet.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frosietheghostie%2Fseaside","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frosietheghostie%2Fseaside","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frosietheghostie%2Fseaside/lists"}