mirror of
https://github.com/fadden/6502bench.git
synced 2024-08-19 20:29:36 +00:00
Switched from XHTML to HTML5. Added formatting for menu items and keyboard shortcuts. Made various minor edits to the text.
119 lines
4.9 KiB
Markdown
119 lines
4.9 KiB
Markdown
# SourceGen Test Data #
|
|
|
|
This directory contains various regression tests.
|
|
|
|
NOTE: some tests may fail if you use a version of the assembler that is
|
|
different from the one used to generate the expected output. The current
|
|
set was generated for:
|
|
|
|
* 64tass v1.56.2625
|
|
* ACME v0.97
|
|
* cc65 v2.18
|
|
* Merlin 32 v1.0
|
|
|
|
|
|
## Generator/Assembler Tests ##
|
|
|
|
Files with names like "10000-nifty-test" are regression test data files
|
|
for the code generator. The test harness identifies them by filename
|
|
pattern: five digits, a hyphen, then one or more alphanumeric and
|
|
hyphens. Files with a '.' or '_' are ignored.
|
|
|
|
If the leading number is between 10000 and 19999, inclusive, the test file
|
|
will be loaded as a new project. A load address of $1000 is assumed.
|
|
The CPU type is determined by the last digit: 0 for 6502, 1 for 65C02,
|
|
2 for 65816, and 3 for W65C02. Undocumented opcodes are enabled. As with
|
|
all new projects, the first byte will be tagged as a code start point. The
|
|
entry flags are currently set to emulation mode, but tests should not rely
|
|
on that.
|
|
|
|
If the leading number is 20000 or greater, the test file will be loaded as
|
|
a saved project. A file with the same name plus a ".dis65" extension will
|
|
be opened as the project file.
|
|
|
|
### Overriding Settings ###
|
|
|
|
All tests are run with a fixed set of app settings, so that the tests look
|
|
the same regardless of how the assemblers are configured. For example,
|
|
upper-case conversion is disabled, and cycle counts are not shown.
|
|
|
|
Sometimes a test will want to exercise one of these settings, so we need
|
|
a way to tell the test harness to override the default. We do this by
|
|
creating project symbols.
|
|
|
|
| Name | Value | Description
|
|
| ---------------------- | ----- | -------------------------------------------|
|
|
| __ENABLE_LABEL_NEWLINE | any | Puts long labels on their own line |
|
|
| __ENABLE_CYCLE_COUNTS | any | Adds cycle count to end-of-line comments |
|
|
|
|
### Execution ###
|
|
|
|
With debug features enabled, you can open the test runner from the menu
|
|
with Debug > Source Generation Tests. Click "Run Test" to run all tests.
|
|
|
|
For each test, the test harness will create a new project or open the
|
|
project file. For every known assembler, the test harness will generate
|
|
source code, and compare it to the corresponding entry in the Expected
|
|
directory. If they don't match exactly, a failure is reported for the
|
|
generation phase. (These are text files, so the line terminators are not
|
|
required to match.) Next, the generated sources are fed to the appropriate
|
|
cross-assembler, whether or not the sources matched expectations. If the
|
|
assembler reports success, the output file is compared to the original data
|
|
file. If these match, success is reported for the assembly phase.
|
|
|
|
The top window in the test harness shows a summary of success or failure.
|
|
The bottom window shows details reported for each individual test. Use
|
|
the drop list to select which test is shown.
|
|
|
|
The generated sources and assembled output is placed into a temporary
|
|
directory inside SGTestData that is named after the test. For example,
|
|
test 10000-allops-value-6502 will have all of its generated output in a
|
|
directory called "tmp10000". If all parts of the test are successful, the
|
|
directory will be removed. If generation or assembly fails, or if you check
|
|
the "retain output" box in the test harness, the directory and its contents
|
|
will remain. This allows you to examine the outputs when investigating
|
|
failures.
|
|
|
|
As a safety measure, the directory will NOT be removed if it contains files
|
|
that the test harness doesn't recognize.
|
|
|
|
### Updating Tests ###
|
|
|
|
If you want to add or update a test, follow these steps:
|
|
|
|
1. Make the changes to the test data file and test project file.
|
|
2. Run the test harness. The generation test will fail and leave output in
|
|
the tmpNNNNN directory. Make sure the assembly test is succeeding.
|
|
3. After verifying that the generated sources look correct, copy them
|
|
into the Expected directory, replacing any existing copies.
|
|
4. Run the test harness. This should now report success, and will
|
|
remove the tmpNNNNN directory.
|
|
|
|
Be sure to have the version of the cross-assembler identified at the top
|
|
of this document configured.
|
|
|
|
|
|
### Other Notes ###
|
|
|
|
The original source code used to generate the test cases can be found
|
|
in the Source directory. The test harness does not use these files. If
|
|
you want to update a test file, you will need to run the assembler
|
|
yourself. The assembler used is noted in a comment at the top of the file.
|
|
|
|
The code is not required to do anything useful. Many of the test cases
|
|
would crash or hang if executed.
|
|
|
|
|
|
## FunkyProjects ##
|
|
|
|
This is a collection of project files with deliberate errors. These exist
|
|
to exercise the load-time error reporting. See the README in that directory
|
|
for a full explanation.
|
|
|
|
|
|
## Visualization ##
|
|
|
|
Some test projects and data files for exercising the visualization generators.
|
|
Not part of a formal test; load the projects and eyeball the results.
|
|
|