Created by Chris Torrence (chris<at>ct6502<dot>org), with significant contributions from Michael Morrison (codebythepound<at>gmail<dot>com). Thanks also to the Apple II community for feedback, bug reports, and feature requests.
This project was originally create using Create React App and was then migrated to vite following these steps.
Be sure to install node.js and npm on your system using either nvm (the Node version manager) or the Node installer. Either one should work fine.
In the project directory, to run the app in development mode:
npm install
npm start
This should automatically open your browser to http://localhost:6502.
The page will reload when you make changes. You may also see any lint errors in the console.
You can append parameters to the URL (to control say the emulator speed or the starting disk image) by using the following syntax:
npm start --urlparam=<parameters>
For example:
npm start --urlparam=speed=fast#Replay
This will start the emulator in fast mode and load the Total Replay disk image.
Runs all of the jest unit tests:
npm test
Run a single test:
npm test memory.test.ts
Run in watch mode:
npm test -- --watch
To builds the app for production:
npm install
npm run buildThis will create the build in the dist folder.
It correctly bundles React in production mode and optimizes the build for best performance. The build is minified and the filenames include hash values. These hashes force the browser to reload when the file content changes, ensure that the filenames are unique, and also verify the integrity of the file.
There should be no errors generated. If you see errors, be sure to check that your version of node and npm are up to date. If there are still errors, contact the author.
Note: This project uses Github Pages to host the emulator. You should not need to build the package, except to confirm that the build will work correctly when changes are committed.
When you check in code changes to Github, Github will automatically run one of two workflows. The main-build-deploy.yml workflow will run for code checked into the main branch, while pull-request-build-only.yml will run for pull requests. The main-build-deploy.yml workflow should fire off two Github Actions. The first will build and test the code, while the second (using npm run deploy) will deploy the build to Github Pages.
For the Github Actions, the secrets.GH_SECRET needs to be set to your current Personal Access Token. This needs to be regenerated each year. To do this, go under your main profile, choose Developer Settings -> Personal access tokens -> Fine-grained tokens, choose "gp-pages deploy". Choose an expiration date for one year in the future. Copy the new PAT and save it somewhere safe. Once you have the new Github PAT, you can set it on the repo. Under Settings, choose "Secrets and variables" -> "Actions", then click Edit on the GH_SECRET.
https://www.hostingadvice.com/how-to/update-npm-packages/
npm install -g npm-check-updates
npm outdated
ncu --upgrade
npm installThe launch.json file contains the debug configurations and should not need to be modified.
To debug the emulator, open the Run/Debug panel and click the "Launch Chrome" play button. Or simply press the F5 key.
Any debug output or console.log messages should appear in the Debug Console. You should also be able to set breakpoints in the code, examine variable values, and execute simple JavaScript statements in the Debug Console.
Using Android Studio, create a new device (like a phone), start the device.
Start the emulator with npm run host to make the application available to the network. You must do this - you cannot run on localhost:6502 or 10.0.2.2:6502 on Android (it's some conflict with vite and chrome).
Navigate to the provided URL - it will be something like 10.0.0.xxx:6502.
On your Desktop Chrome, go to chrome://inspect/#devices and then choose the appropriate "Remote Target".
https://developer.apple.com/documentation/safari-developer-tools/inspecting-ios
In VS Code, add breakpoints to the test code. Then open up package.json, hover over
the "test" script, and select 'Debug Script'.
Gamepads will only work with a secure (https) context. To enable https when running from localhost, you need to generate a certificate and install it on your system.
Install the Github Changelog Generator by running:
gem install github_changelog_generatorYou may need to update to Ruby v3.x to install this gem.
Go through the commits, and add any missing tags. For a given commit sha (say 1befdec), checkout the commit, force the date to be the commit date, and then add the tag:
git checkout 1befdec
GIT_COMMITTER_DATE="$(git show --format=%aD | head -1)"
git tag -a v2.6 -m"v2.6"
git push origin --tags
git checkout mainIf you don't already have one, generate a Github token to run the Changelog Generator script with authentication. You only need "repo" scope for private repositories.
Now run the script:
github_changelog_generator --token xxxxx -u ct6502 -p apple2tsTo make a ROM image, save the raw binary data from the C000-FFFF ROM in a single file. Then convert the file to a Base64 encoding. On the Mac, you can use the following command:
openssl base64 -in rom_2e.bin -out rom_2e.base64.tsFinally, edit the .ts file, and change the file to be an exported string variable by prepending:
export const rom=`Don't forget to append the trailing back quote ` at the end of the file.
Assembly Lines: The Complete Book
