You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+17-10Lines changed: 17 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,11 +14,18 @@ If you'd rather not build from source, check out the [Releases](https://github.c
14
14
Asar can also be built as a DLL. This makes it easier and faster to use in other programs (such as a sprite insertion tool). You can find documentation on the DLL API in the respective bindings (asardll.h, asar.cs, asar.py).
15
15
16
16
## Asar as a static library
17
-
Asar can also be build as a static library. All "out-facing" functions are in interface-lib.h. This is useful for embedding Asar in other programs which don't want to use DLLs. The easiest way to add asar as a static library to your project, assuming you are using CMake (at least 3.11), is to use [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html) to fetch the source code, then add the following to your CMakeLists.txt:
17
+
Asar can also be built as a static library. All "out-facing" functions are in interface-lib.h. This is useful for embedding Asar in other programs which don't want to use DLLs. The easiest way to add asar as a static library to your project is to add it as a git submodule
target_link_libraries(YourTarget PUBLIC asar-static)
20
27
```
21
-
to be able to include the header files. It is also recommended to add `set(ASAR_TESTING_DISABLED TRUE)` to your CMakeLists.txt to disable building tests.
28
+
to be able to include the header files. It is also recommended to turn off every build in target in asar except the static one using the appropriate CMake options. You will need to make sure that your project has an Asar compatible license.
22
29
23
30
## Folder layout
24
31
*`docs` contains the source of the manual and changelog.
@@ -46,7 +53,7 @@ These two characters should precede each test line, so that Asar sees them as co
46
53
* 2 hex digits - a byte for it to check for
47
54
* You can specify more than one, like in the examples below, and it will automatically increment the offset.
48
55
* A line starting with `+` tells the testing app to patch the SMW ROM instead of creating a new ROM
49
-
*`errEXXXX` and `warnWXXXX` (where `XXXX` is an ID number) means that the test is expected to throw that specific error or warning while patching. The test will succeed only if the number and order of errors and warnings thrown exactly matches what's specified here. Be wary that Asar uses multiple passes and throws errors and warnings across multiple of them. This can make the actual order in which errors and warnings are thrown a bit unintuitive.
56
+
*`errE{name}` and `warnW{name}` (where `{name}` is the name of an error or warning) means that the test is expected to throw that specific error or warning while patching. The test will succeed only if the number and order of errors and warnings thrown exactly matches what's specified here. Be wary that Asar uses multiple passes and throws errors and warnings across multiple of them. This can make the actual order in which errors and warnings are thrown a bit unintuitive.
50
57
51
58
In addition to the format mentioned above, it's also possible to check for user prints a patch is expected to output (by `print`, `error`, `warn` or `assert` commands). This is done by starting the line with one of the following sequences:
52
59
```
@@ -68,17 +75,17 @@ This line tests that `22`, `20`, `80` and `90` were written to the ROM offset `0
68
75
;`007606 22 20 80 90
69
76
```
70
77
71
-
This line tests that assembling the patch throws error `5117` twice and warning `1030` once.
78
+
This line tests that assembling the patch throws error `Eunknown_command` twice and warning `Wfeature_deprecated` once.
72
79
```
73
-
;`errE5117
74
-
;`errE5117
75
-
;`warnW1030
80
+
;`errEunknown_command
81
+
;`errEunknown_command
82
+
;`warnWfeature_deprecated
76
83
```
77
84
78
-
This line tests that the byte `FF` was written to the start of the ROM, that the string `This is a print.` was printed and that the string `This is a user error.` was output via the error command (which itself also causes error `E5159`to be thrown once).
85
+
This line tests that the byte `FF` was written to the start of the ROM, that the string `This is a print.` was printed and that the string `This is a user error.` was output via the error command (which itself also causes error `Eerror_command`to be thrown once).
Copy file name to clipboardExpand all lines: docs/changelog/index.html
+36Lines changed: 36 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -45,13 +45,23 @@ <h3>Contributors:</h3>
45
45
<ul>
46
46
<li>RPG Hacker</li>
47
47
<li>randomdude999</li>
48
+
<li>p4plus2</li>
49
+
<li>Atari2</li>
48
50
</ul>
49
51
52
+
<h3>Notes:</h3>
53
+
<ul>
54
+
<li>The primary purpose of this release is to be a stepping stone towards Asar 2.0. For this purpose, a lot of features have been deprecated and will now throw warnings. Please fix any of those warnings you come across in your patches to assure they will still assemble in Asar 2.0.</li>
55
+
</ul></div>
56
+
50
57
<h3>New features:</h3>
51
58
<ul>
52
59
<li>The Asar test suite can now verify user-printable strings. (RPG Hacker)</li>
53
60
<li>The <code>error</code>, <code>warn</code> and <code>assert</code> commands now support the same functions as the print command. (RPG Hacker)</li>
54
61
<li>Static labels (i.e. labels that don't move between passes) can now be used in more places, including if statements. (RPG Hacker)</li>
62
+
<li>Asar can be built as a static library. (Atari2)</li>
63
+
<li>Asar now uses named warnings and errors instead of magic numbers as identifiers. (p4plus2, RPG Hacker)</li>
64
+
<li>Variadic macro parameters now use the syntax <codeclass="65c816_asar"><...[math]></code>, which makes them less ambiguous and helps prevent syntax parsing bugs. (RPG Hacker)</li>
55
65
</ul>
56
66
57
67
<h3>Bug fixes:</h3>
@@ -62,6 +72,32 @@ <h3>Bug fixes:</h3>
62
72
<li>For invalid table files, Asar now prints the line number of the first invalid entry. (RPG Hacker)</li>
63
73
<li>When Asar generates addr-to-line mappings, it now includes multiple addresses for pseudo opcodes like "asl #4". (RPG Hacker)</li>
64
74
<li><code>'''</code> and <code>';'</code> are now valid can now be used without causing errors. (randomdude999, RPG Hacker)</li>
75
+
<li>Fixed some edge case bugs in Asar's virtual filesystem (usable via the DLL) on Windows. (Atari2)</li>
76
+
</ul></div>
77
+
78
+
<h3>Deprecated features:</h3>
79
+
<ul>
80
+
<li>Warning and error IDs: Use new name strings instead.</li>
81
+
<li><code>JMP.l</code>: Use <code>JML</code> instead.</li>
82
+
<li>Quoted symbolic arguments to functions (e.g. <code>sizeof("my_struct")</code>): Remove the quotes (<code>sizeof(my_struct)</code>).</li>
83
+
<li>Redefining previously defined functions.</li>
84
+
<li><code>math round</code> and <code>math pri</code>: Use parentheses and explicit rounding where xkas-style math emulation is needed instead.</li>
85
+
<li><code>.d</code> length specifier on opcodes.</li>
86
+
<li><code>if !condition</code> to negate conditions: Use <code>if not(condition)</code> instead.</li>
87
+
<li>While blocks ending with <code>endif</code>: Use <code>endwhile</code> instead.</li>
88
+
<li><code>bankcheck on</code>: Use <code>bankcheck full</code> or <code>bankcheck half</code> instead.</li>
89
+
<li><code>rep</code> to repeat commands: Use while loops or unrolled loops instead.</li>
<li><code>table</code> command: Assign characters directly instead, like <code>'a' = $00</code>.</li>
92
+
<li>Labels in <code>padbyte</code> or <code>fillbyte</code> commands.</li>
93
+
<li><code>spc700-raw</code> architecture: Use <code>spc700</code> with <code>norom</code> instead.</li>
94
+
<li><code>fastrom</code>: Has never actually worked and can be removed.</li>
95
+
<li><code>header</code>: Doesn't do anything and can be removed.</li>
96
+
<li>Non-UTF-8 source files: Re-save your source files as UTF-8 in a text editor of choice.</li>
97
+
<li><code>;@command</code> and <code>@command</code> notation: Use <code>command</code> instead.</li>
98
+
<li>Wrapping defines to resolve in quotes (e.g. <code>db "!define"</code>): The quotes aren't needed (<code>db !define</code>).</li>
99
+
<li>Single-line/inline if statements: Use full if blocks with an <code>if</code>/<code>endif</code> pair instead.</li>
100
+
<li><codeclass="65c816_asar"><math></code> syntax for variadic macro parameters: Use <codeclass="65c816_asar"><...[math]></code> insread.</li>
In addition to named substitutions if the variadic token <codeclass="65c816_asar">...</code> is specified as the last parameter asar will allow an arbitrary number of parameters after all prior parameters have been satisfied.
2442
-
To access unnamed arguments of a variadic function they are declared numerically starting from 0 up to the number of provided parameters. To access the number of provided variadic arguments one may use <codeclass="65c816_asar">sizeof(...)</code>.
2442
+
To access unnamed parameters of a variadic macro, use the syntax <codeclass="65c816_asar"><...[{math}]></code>, where <codeclass="65c816_asar">math</code> is any math expression evaluating to the index of a variadic parameter. These are declared numerically starting from 0 up to the number of provided parameters. To access the number of provided variadic arguments one may use <codeclass="65c816_asar">sizeof(...)</code>.
2443
2443
Lastly, it is important to note that while traditionally macros do not parse defines at their creation variadic macros will. This is to allow iteration of arguments by using defines.
0 commit comments