{"id":15060480,"url":"https://github.com/zeh/dasmjs","last_synced_at":"2025-06-28T08:32:32.824Z","repository":{"id":138108514,"uuid":"77957458","full_name":"zeh/dasmjs","owner":"zeh","description":"An emscripten-compiled version of the dasm macro assembler","archived":false,"fork":false,"pushed_at":"2018-12-16T01:31:08.000Z","size":1101,"stargazers_count":10,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-14T22:44:16.222Z","etag":null,"topics":["assembler","assembly","atari","atari2600","dasm","dasm-macro-assembler","emscripten","mos-6502","typescript"],"latest_commit_sha":null,"homepage":null,"language":"Assembly","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/zeh.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":"2017-01-03T22:06:27.000Z","updated_at":"2024-02-15T15:45:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"f72fbdaa-ae71-47f3-b287-feddf2bbf201","html_url":"https://github.com/zeh/dasmjs","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/zeh/dasmjs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeh%2Fdasmjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeh%2Fdasmjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeh%2Fdasmjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeh%2Fdasmjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zeh","download_url":"https://codeload.github.com/zeh/dasmjs/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeh%2Fdasmjs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262400836,"owners_count":23305382,"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","atari","atari2600","dasm","dasm-macro-assembler","emscripten","mos-6502","typescript"],"created_at":"2024-09-24T22:59:17.587Z","updated_at":"2025-06-28T08:32:32.807Z","avatar_url":"https://github.com/zeh.png","language":"Assembly","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The dasm macro assembler (for JavaScript)\n\n[![npm](https://img.shields.io/npm/v/dasm.svg)](https://www.npmjs.com/package/dasm)\n[![Dependency Status](https://david-dm.org/zeh/dasmjs.svg)](https://david-dm.org/zeh/dasmjs)\n\nThis is an [emscripten](https://github.com/kripken/emscripten)-compiled version of the [dasm macro assembler](http://dasm-dillon.sourceforge.net/).\n\nThe dasm macro assembler transforms assembly code into 6502-compatible executable binary code. Since this is a JavaScript port of dasm, it allows that compilation process from JavaScript programs; more especifically, it can be used to create ROMs for Atari VCS 2600 and Fairchild Channel F (and others!) from a string containing dasm-compatible assembly source code.\n\nIn other words, it turns something like this:\n\n```assembly\n; Pick the correct processor type\n        processor 6502\n; Basic includes\n        include \"vcs.h\"\n        include \"macro.h\"\n; Start address\n        org $f000\n; Actual instructions\nstart   SEI\n        CLD\n        LDX  #$FF\n        TXS\n        LDA  #$00\n        ...\n```\n\n...into its equivalent byte code:\n\n```assembly\nf000 78\nf001 d8\nf002 a2 ff\nf004 9a\nf005 a9 00\n...\n```\n\nAmong other features, dasm sports:\n\n* fast assembly\n* several binary output formats available\n* expressions using [] for parenthesis\n* complex pseudo ops, repeat loops, macros, etc\n\nOn top of that, this JavaScript port also offers:\n\n* More high-level parsing of symbols and labels' information (including declaration origin, type, etc)\n* A direct library interface for assembling (rather than a command-line interface)\n\nThis port of dasm was created so I could have dasm compiling working in [vscode-dasm](https://github.com/zeh/vscode-dasm), my Visual Studio Code extension that aims to allow Atari development and debugging from within Visual Studio Code.\n\n## Technical information\n\nThis package uses version 2.20.11 of dasm. It supports the following processor architectures:\n\n* 6502 (and 6507)\n* 68705\n* 6803\n* HD6303 (extension of 6803)\n* 68HC11\n\nThis specific port was built on Linux (err, Windows 10 bash) from the dasm source using emscripten 1.37.0. Check the [dasm folder](https://github.com/zeh/dasmjs/tree/master/dasm) for the script that was used to compile `dasm.js`, including its pre/post-JS includes to wrap the code in a module function and return its results in a more usable way.\n\n## Usage\n\nInstall with NPM:\n\n```shell\nnpm install dasm --save\n```\n\nOr with Yarn:\n\n```shell\nyarn add dasm\n```` \n\n\nImport as a module:\n\n```JavaScript\nimport dasm from \"dasm\"; // ES6\nvar dasm = require(\"dasm\").default; // ES5\n```\n\nFinally, convert code to a binary data ROM. Instead of forcing developers to use a command line-like interface, the function that wraps the emscripten module provides a modern interface to dasm:\n\n```JavaScript\n// Read utf-8 assembly source\nconst src = \"...\";\n\n// Run with the source\nconst result = dasm(src);\n\n// Read the output as a binary (Uint8Array array)\nconst ROM = result.data;\n```\n\n### Advanced usage\n\nAdvanced options can be passed to the `dasm` call via an options parameter. For example:\n\n```JavaScript\n// Create a rom using the typical Atari VCS 4096-byte format\ndasm(src, { format: 3 });\n\n// Just create a rom without exporting symbols or lists\ndasm(src, { quick: true });\n\n// Typical assembly to create an Atari VCS ROM with built-in .h includes\ndasm(src, { format: 3, quick: true, machine: \"atari2600\" });\n\n// Pass original command-line parameters\ndasm(src, { parameters: \"-f3 -p2 -v4 -DVER=5\" });\n```\n\nThese are all the options currently parsed:\n\n* `format`: binary output format. Dictates the size and arrangement of the generated ROM.\n  * `1` (default): output includes a 2-byte origin header.\n  * `2`: random access segment format. Output is made of chuncks that include a 4-byte origin and length header.\n  * `3`: raw format. Just the data, no headers.\n* `quick`: boolean. If set to `true`, don't export any symbol and pass list as part of its returned data. Defaults to false.\n* `parameters`: string. List of switches passed to dasm as if it was being called from the command line.\n* `include`: key-value object, or `IIncludeInfo[]`. This is a list of files that should be made available for the source code to `include`. If an objct, the key contains the complete file path, and the value contains its content, either as a string or an `Uint8Array` for binary files. It can also be an array of include file info, as returned by `resolveIncludes()` (more on that below).\n* `machine`: target machine as a string. Similarly to dasm's `-I` switch, this picks a list of (embedded) files to make available to the `include` command.\n  * `\"atari2600\"`: includes dasm's own `atari2600/macro.h` and `atari2600/vcs.h` files.\n  * `\"channel-f\"`: includes dasm's own `channel-f/macro.h` and `channel-f/ves.h` files.\n\nFor more examples, check the [test files](test) on reference implementations of typical compilations.\n\nAlso check [the dasm documentation](https://github.com/zeh/dasmjs/blob/master/dasm/src/doc/dasm.txt) for a list of all command-line switches available, for more information on binary formats, and for a list of all macros available.\n\n### Returned object\n\nThe object returned by the `dasm` function has more than just a binary ROM. This is what's available:\n\n* `data`: `Uint8Array`. The exported ROM, as a list of integers.\n* `output`: `string[]`. All data written by dasm to `stdout`.\n* `list`: `ILine[]`. A list of all lines available in the source code, and their parsed info (address, bytecode, comments, command, etc).\n* `listRaw`: `string`. The raw output of the list file (equivalent to the `-L` switch).\n* `symbols`: `ISymbol[]`. A parsed list of all symbols (labels and constants) defined by the source code.\n* `symbolsRaw`: `string`. The raw output of the symbols file (equivalent to the `-s` switch).\n* `exitStatus`: `number`. A code indicating the exit status of the assembler module. Normally `0` if exited without problems, or `1` if aborted prematurely.\n* `success`: `boolean`. `true` if successfully compiled, `false` if otherwise.\n\nOf specially note are the `list` and `symbols` objects. Those include parsed information about the source code, including line-specific error messages.\n\n### Convenience functions\n\nFor convenience, this library also exposes one additional function that can be useful when processing assembly sources, `resolveIncludes`. This function parses all `include`, `incbin` and `incdir` pseudo-ops from the source, and resolves them to their respective file URIs (in POSIX format) and content. Use it like so:\n\n```JavaScript\nimport { resolveIncludes } from \"./../lib/index\";\n\nconst includes = resolveIncludes(source, getFile = undefined, baseFolder = \"\");\n```\n\nThese are its parameters:\n\n* `source`: `string` containing assembly source code. The same source that is passed to the `dasm()` call.\n* `getFile`: a `function` that takes two parameters: `sourceEntryRelativeUri` (relative location of a file as `string`) and `isBinary` (whether it's a binary include, as `boolean`) and returns contents of that file (as either a `string` for text files, an `Uint8Array` for binary files, or `undefined` for files that were not found).\n\n  This function is optional and should be used as a convenience function to allow `resolveIncludes` to parse file contents and children includes (includes of includes). It ommitted, `resolveIncludes` returns a list of includes for the original source file without their contents (but with their best guess at the file's actual `uri`).\n\n  When using dasm inside node, a typical implementation of `getFile` that just gets file contents from the file system (`fs`) is as such:\n\n  ```JavaScript\n  function bufferToArray(b) {\n      const arr = new Uint8Array(b.length);\n      return arr.map((v, i) =\u003e b[i]);\n  }\n\n  function getFile(sourceEntryRelativeUri, isBinary) {\n      const fullUri = path(__dirname, sourceEntryRelativeUri);\n      if (fs.existsSync(fullUri)) {\n          if (isBinary) {\n              return bufferToArray(fs.readFileSync(fullUri));\n          } else {\n              return fs.readFileSync(fullUri, \"utf8\");\n          }\n      }\n  }\n  ```\n  It's important to check for a file existence because `getFile` might get called with uris that do not exist. This inevitable if the `incdir` pseudo-op is used in the code.\n* `baseFolder`: uri `string` to be used when generating possible include file uris.\n* `recursive`: `boolean` on whether the resolution should be recursive or not. The default is `true`, in which case every included file will also be parsed for `includes` of its own.\n\nThis function returns an array of `IIncludeInfo`, each containing:\n\n* `line`: `number`. Line in the source file where this resource filename is.\n* `column`: `number`. Column in the source file where this resource filename is.\n* `entryRelativeUri`: `string`. The uri of this include, relative to the original entry source (and its `baseFolder`, if any).\n* `parentRelativeUri`: `string`. The uri actually used when including this file.\n* `isBinary`: `boolean`. Whether it's a binary file (used with `incbin`) or a text file (used with `include`).\n* `includes`: `IIncludeInfo[]`. Child dependencies of this file.\n* `contents`: `string|Uint8Array|undefined`. Contents of this file: a `string` if text, `Uint8Array` if binary, or `undefined` if not found or if `getFile` was not passed.\n\n### More information\n\nTypeScript definitions are included with this distribution, so TypeScript projects can use the module and get type checking and completion for all `dasm` calls. Non-TypeScript JavaScript developers using Visual Studio Code will also benefit from auto-completion without any change thanks to VSC's [Automatic Type Acquisition](http://code.visualstudio.com/updates/v1_7#_better-javascript-intellisense).\n\nTypeScript projects also have the benefit of being able to import the interfaces themselves, if needed:\n\n```typescript\n// dasm() options\nimport { IOptions } from \"dasm\";\n\n// dasm() return object\nimport { IDasmResult } from \"dasm\";\n\n// Other interfaces used by the IDasmResult object\nimport { ISymbol, ILine } from \"dasm\";\n\n// The include info returned by resolveIncludes(), or passed to dasm() for inclusion\nimport { IIncludeInfo } from \"dasm\";\n```\n\n## Todo and ideas\n\n* Allow asynchronous assembly (run as a worker?)\n* Allow asynchronous `resolveIncludes`?\n* Command-line package? (`dasm-cli`)\n  * Allow direct FS use?\n\nContributions are welcome.\n\n## Changelog\n\nCheck [the release list](https://github.com/zeh/dasmjs/releases) for a list of what has changed in every new version.\n\n## Acknowledgements\n\nThe dasm macro assembler was created by by Matthew Dillon. It was further augmented by Olaf \"Rhialto\" Seibert, Andrew Davie, and Peter H. Froehlich.\n\n## License\n\nThis follows dasm itself and uses the [GNU Public License v2.0](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeh%2Fdasmjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzeh%2Fdasmjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeh%2Fdasmjs/lists"}