About CSASM - absoluteAquarian/CSASM GitHub Wiki

CSASM, short for C# Assembler, is a stack-based language inspired by the assembler languages of old, such as Z80 and 6502 Assembler.

CSASM's compiler (csasm.exe) and core features (CSASM.Core.dll) are both written in C#, hence the name.

The compiler is run by running the csasm.exe file or via dotnet CSASM.dll. The compiler's arguments are specified below:

csasm.exe <file> [--outfile <out file>] [--report <true/false>] [--nestdir <true/false>]

dotnet CSASM.dll <file> [--outfile <out file>] [--report <true/false>] [--nestdir <true/false>]

• <file> is the file that is being compiled. Either the file name itself or a path leading up to and including the file can be used.
  • The path to the file cannot be rooted (starts with a drive indicator like C:\\ or D:\\)
  • Examples:
    • csasm.exe myFile.csa
    • csasm.exe ..\myOtherFile.csa
• --outfile is an optional parameter which specifies what the resulting executable is called and where it is located (<out file>). The output file must have the .exe extension
  • Examples:
    • csasm.exe myFile.csa --outfile MyDll.dll
    • csasm.exe myFile.csa --outfile ..\MyDll.dll
    • csasm.exe myFile.csa --outfile "My Folder\MyDll.dll"
  • If this parameter is not used, the executable's name will default to what's after the .asm_name token in the source file. If said token is not in the source file, the executable's name will default to csasm_prog
  • If specified, this parameter must be set as a .dll file.
  • Compiled files are run by running dotnet MyDll.dll
• --report is an optional parameter which, when used, causes the compiler to report the compilation process to the console
• --nestdir is an optional parameter which, when used, causes the compiled program and its files to end in a nested folder relative to where the compiler is run from

The compiler is run by running the csasm.exe file. The compiler's arguments are specified below:

csasm.exe <file> [-out:<out file>] [-report]

• <file> is the file that is being compiled. Either the file name itself or a path leading up to and including the file can be used.
  • The path to the file cannot be rooted (starts with a drive indicator like C:\\ or D:\\)
  • Examples:
    • csasm.exe myFile.csa
    • csasm.exe ..\myOtherFile.csa
• -out: is an optional parameter which specifies what the resulting executable is called and where it is located (<out file>). The output file must have the .exe extension
  • Examples:
    • csasm.exe myFile.csa -out:MyExe.exe
    • csasm.exe myFile.csa -out:..\MyExe.exe
    • csasm.exe myFile.csa "-out:My Folder\MyExe.exe"
  • If this parameter is not used, the executable's name will default to what's after the .asm_name token in the source file. If said token is not in the source file, the executable's name will default to csasm_prog
• -report is an optional parameter which, when used, causes the compiler to report the compilation process to the console

The <file> parameter must be the first argument. The optional arguments can be in any order.

The stack is a fixed-size collection of objects (see CSASMStack.cs) used during the execution of a CSASM program.

The stack's size can be set using the .stack token. If this token is not used, the stack defaults to a size of 1000.

The compiler requires the files CSASM.Core.dll, dnlib.dll, System.CodeDom.dll, System.CommandLine.dll, System.CommandLine.DragonFruit.dll, System.CommandLine.Rendering.dll, CSASM.deps.json and CSASM.runtimeconfig.json.

Any generated .dll files need the files they were generated with in order to run via dotnet.

The Headers folder needs to be in the same directory that the compiler is in, otherwise the .include preprocessor directive will fail when trying to reference standard header files (stdlib.csah, stdio.csah, etc.).

Both the compiler and any generated executables need the CSASM.Core.dll file to be in the same directory.

However, only the compiler needs the dnlib.dll file.

The Headers folder needs to be in the same directory that the compiler is in, otherwise the .include preprocessor directive will fail when trying to reference standard header files (stdlib.csah, stdio.csah, etc.).

Running a CSASM program is done like any other .exe file, but with a few caveats:

Program.exe [args] [-verbose] [-reportstack]

args is the arguments passed to the function and can be accessed via the $args register. If args is defined, then any debug flags MUST be after it, otherwise the program throws an exception.

-verbose is the "Debugging Output" flag. When used, most instructions will print what was on the stack before they were called to a verbose.txt file in the same directory as the executable.

-reportstack is the "Stack Reporting" flag. When used, any pushes or pops from the stack will be printed to the aforementioned verbose.txt file.