{"id":19324682,"url":"https://github.com/knightos/sass","last_synced_at":"2025-10-28T06:39:56.983Z","repository":{"id":148103842,"uuid":"6285337","full_name":"KnightOS/sass","owner":"KnightOS","description":"SirCmpwn's Assembler","archived":false,"fork":false,"pushed_at":"2015-03-11T19:40:19.000Z","size":581,"stargazers_count":6,"open_issues_count":0,"forks_count":7,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-02T03:43:16.990Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":false,"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/KnightOS.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}},"created_at":"2012-10-18T21:04:41.000Z","updated_at":"2021-02-26T19:11:03.000Z","dependencies_parsed_at":"2023-03-27T14:28:19.551Z","dependency_job_id":null,"html_url":"https://github.com/KnightOS/sass","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KnightOS%2Fsass","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KnightOS%2Fsass/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KnightOS%2Fsass/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KnightOS%2Fsass/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KnightOS","download_url":"https://codeload.github.com/KnightOS/sass/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250308676,"owners_count":21409315,"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":[],"created_at":"2024-11-10T02:06:19.240Z","updated_at":"2025-10-28T06:39:51.953Z","avatar_url":"https://github.com/KnightOS.png","language":"C#","readme":"# SirCmpwn's Assembler\n\nSirCmpwn's Assembler (sass) is a multiplatform, two-pass assembler written in C#. Presently, it supports\nz80 out of the box, as well as any user-provided instruction sets. It runs on Windows, Linux and Mac, as\nwell as several other platforms in the form of a library.\n\n## Using SASS\n\nOn Linux or Mac, make sure that you have Mono installed, and prepend any commands to run Organic with\n\"mono\", similar to running Java programs. Note that the default Mono on Ubuntu isn't the full install,\nremove it and install \"mono-complete\".\n\n### Command Line Usage\n\nUsage: sass.exe [parameters] [input file] [output file]\n\n[output file] is optional, and [input file].bin will be used if it is not specified.\n\n#### Parameters\n\nYou may customize sass's usage at the command line with a number of parameters.\n\n**--encoding \\[name]**: Sets the string encoding to use for string literals. Note that .asciiz and related directives\n  will use the specified encoding, not ASCII. The default is \"utf-8\".\n\n**--help**: Displays information on sass usage and basic documentation. *Aliases: -h -? /? /help -help*\n\n**--include \\[path(s)]**: Modifies the include path. This should be a semicolon-delimited list of paths to look\n  for files included with \u003c\u003e in. Example: `--include \"/foo;/bar\"` *Aliases: --inc*\n\n**--input-file \\[file]**: An alternative way to specify the input file. *Aliases: --input*\n\n**--instruction-set \\[set]**: Specifies the instruction set to use. May be a key to reference an internal set\n  (see [below](#supported-architectures)), or a path to a user-specified instruction set file. *Aliases: --instr*\n\n**--listing \\[file]**: Specifies a file to output a listing to. *Aliases: -l*\n\n**--list-encodings**: Lists all available string encodings and their keys for use in --encoding. This will terminate\n  sass without assembling any files.\n\n**--output-file \\[file]**: An alternative way to specify the output file. *Aliases: --output*\n\n**--symbols [file]**: Outputs all labels and their addresses to a file using `.equ` so that they may be included\n  again elsewhere. *Aliases: -s*\n\n**--verbose**: Outputs a listing to standard output after assembly completion. *Aliases: -v*\n\n## Supported Architectures\n\nOut of the box, sass supports the following architectures:\n\n* z80 [`z80`]\n* *GameBoy Assembly [`LR35902` or `gbz80`]* (Planned)\n\nIn [brackets], the instruction set key is shown for use whith the --instruction-set command line parameter.\nIf not otherwise specified, the default instruction set is z80.\n\nUser-specified instruction sets may be added. *TODO: Document instruction set format*\n\n## Syntax\n\n*All examples are given in z80 assembly*\n\nSASS's assembly syntax attempts to be as close to other popular syntaxes as possible. Here's some example\nz80 code that assembles under SASS:\n\n        ld b, 20 + 0x13\n    label1:\n        inc c\n        djnz label1\n\nSASS is completely case-insensitive, and whitespace may be used as you please. The exception is that\ndropping newlines requires you to add \\ in their place, like so: \"ld a, 1 \\ add a, b\". However, any\nnumber of tabs or spaces in any location is permissible, though \"AD D a, b\" is invalid, as is\n\"ADDa, b\". Labels may use the \"label:\" form (preferred), or the \":label\" form.\n\nAdditionally, SASS supports nearly every form that an instruction may be presented in. For instance, each\nof the following lines of code is acceptable:\n\n    cp a, (ix + 10)\n    cp a, (10 + ix)\n    cp (ix + 10)\n    cp (10 + ix)\n    cp (ix)\n    cp a, (ix)\n\n### Expressions\n\nAnywhere a number is required, you may use an expression. Expressions are evaluated with respect to\norder of operations, using C precedence. The following operators are available:\n\n    * / % + - \u003c\u003c \u003e\u003e \u003c \u003c= \u003e \u003e= == != \u0026 ^ | \u0026\u0026 ||\n\nBoolean operators will assemble to \"1\" if true, or \"0\" if false.\n\n### Relative Addressing\n\nYou may use relative labels, spasm-style, to simplify your code. You may define any number of labels called `_`\nand refer to them with `[-+]*_` to refer to the nearest ones. Add `+` to get the next label, and the next, and so\non, and `-` to refer to previous relative labels.\n\n    _: ; A\n        jp _ ; Refers to B\n        jp -_ ; Refers to A\n        jp ++_ ; Refers to C\n    _: ; B\n        ld a, b\n    _: ; C\n\n### Local Labels\n\nsass allows you to define local labels, which allows you to reuse common label names, such as \"loop\". You may\npreface any label name with \".\" to declare it as local, and it will be local within the prior global label.\nExample:\n\n    global1:\n        ld a, b\n    .local:\n        call .local\n    global2:\n        ld b, a\n    .local:\n        call .local ; Does not cause a Duplicate Name error\n\n### Macros\n\nMacros are defined through `.macro` and may be used in most conditions. To define a macro, use something like\nthis:\n\n    .macro example\n        ld a, b\n    .endmacro\n\nThis defines a parameterless macro called \"example\". You needn't indent the contents of the macro; it's done\nhere for clarity. You may also define parameters:\n\n    .macro example(foo, bar)\n        ld a, foo\n        ld b, bar\n    .endmacro\n\nThis is a simple substitution macro. When called (like `example(a, b)`), 'foo' and 'bar' will be replaced with\n'a' and 'b' respectively. Here's a more in-depth example:\n\n    .macro example(foo, bar)\n        ld a, foo\n        ld b, bar\n    .endmacro\n    .macro add(a, b)\n        a+b\n    .endmacro\n    example(1, 2) ; Becomes ld a, 1 \\ ld b, 2\n    ld a, add(2, 3) ; Becomes ld a, 2+3\n\n## Pre-Processor Directives\n\nDirectives are indicated by a '.' or '#' as the first character, as in \"#include \\\u003cfoo.h\u003e\".\n\n**ascii \"\\[text]\"**: Converts \"text\" to the global string encoding (**not** ASCII) and inserts it into the output.\n\n**asciiz \"\\[text]\"**: Converts \"text\" to the global string encoding (**not** ASCII) and inserts it into the output,\n  postfixed with a zero.\n\n**asciip \"\\[text]\"**: Converts \"text\" to the global string encoding (**not** ASCII) and inserts it into the output,\n  prefixed with its 8-bit length.\n\n**block \\[size]**: Sets aside *size* bytes, all set to 0. See **fill** if you require a value other than 0.\n\n**db \\[value], \\[value], ...**: Inserts any number of 8-bit *values* into the output.\n\n**dw \\[value], \\[value], ...**: Inserts any number of n-bit *values* into the output, where n is the\n  number of bits to a word in the target architecture.\n\n**define \\[key] \\[value]**: Creates a one-line macro, whose name is \"key\" and whose replacement text is \"value\".\n\n**echo \\[message], \\[message], ...**: Echos any number of *messages* to the console at assembly time. If\n  *message* is not a string, it will be treated as an expression and echoed as a number.\n\n**else**: If the matching if, ifdef, or ifndef directive evalulates to false, the code between this and the matching\n  endif directive will be inserted instead.\n\n**endif**: Closes a corresponding if, ifdef, or ifndef directive.\n\n**equ \\[key] \\[value]**: Creates a symbol whose name is \"key\", with \"value\" as the value. \"value\" must be a valid\n  expression.\n\n**fill \\[size], (value)**: Inserts *size* number of *values* into the output. Default *value* is 0.\n\n**if \\[expression]**: If \"expression\" evalutates to zero, all the code until the matching endif directive will be\n  omitted from the output.\n\n**ifdef \\[symbol]**: If \"symbol\" is not defined as a symbol or macro, all the code until the matching endif directive\n  will be omitted from the output.\n\n**include \\[path]**: Inserts the specified file's contents into the assembly. \\[path] may be `\"localfile\"` or\n  `\u003cincludedfile\u003e`, where the former expects the file to be in the current working directory, and the latter\n  looks for any files within the include path specified at the command line.\n\n**list**: Resumes listing.\n\n**nolist**: Stops listing. This stops the assembler from evaluating any code until the corresponding list directive.\n\n**org \\[value]**: Sets the internal program counter to *value*. This does not add to the output, but will affect\n  labels defined later on.\n\n**What's the difference between define and equ?** Define creates a macro. These have more overheard and take longer\nto evaluate during assembly, and should be used sparingly. Equ \"equates\" a name with a value, and creates a symbol,\nwhich has far less overhead. Use this one if you can. One example of where you need to use define is to define a string\nconstant. Here's some example uses of each:\n\n    .define text \"Hello, world\"\n    .equ otherText \"Hello, world\" ; Doesn't work\n    .equ value 0x1234 - 28\n    \n    .asciiz text\n    ld hl, value\n    \n    .define function(arg1, arg2) ld a, arg1 \\ ld b, arg2\n    \n    function(10, 20) ; Becomes ld a, 10 \\ ld b, 20\n    \n    .define add(arg1, arg2) arg1 + arg2\n    \n    ld a, add(10, value) ; Can use symbols in macro invocation\n    \n    .define foo ; Adds a symbol where \"foo\" equals 1 (special case, doesn't create a macro)\n\n# Compiling from Source\n\n**Windows**: \"msbuild\" from the root directory of the project.\n\n**Linux/Mac**: \"xbuild\" from the root directory of the project.\n\n## Help, Bugs, Feedback\n\nIf you need help with KnightOS, want to keep up with progress, chat with\ndevelopers, or ask any other questions about KnightOS, you can hang out in the\nIRC channel: [#knightos on irc.freenode.net](http://webchat.freenode.net/?channels=knightos).\n \nTo report bugs, please create [a GitHub issue](https://github.com/KnightOS/KnightOS/issues/new) or contact us on IRC.\n \nIf you'd like to contribute to the project, please see the [contribution guidelines](http://www.knightos.org/contributing).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknightos%2Fsass","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknightos%2Fsass","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknightos%2Fsass/lists"}