Skip to content

Commit b4bed3c

Browse files
relrelbrelrelb
committed
docs: Improve CONTRIBUTING.md
Make some general adjustments, and better document how to compile ActionScript tests.
1 parent 754579e commit b4bed3c

File tree

1 file changed

+117
-63
lines changed

1 file changed

+117
-63
lines changed

‎CONTRIBUTING.md‎

Lines changed: 117 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -6,23 +6,24 @@ This document serves as a general guide for contributing to Ruffle. Follow your
66

77
## Table of Contents
88

9-
* [Getting Started](#getting-started)
10-
* [Ways to Contribute](#ways-to-contribute)
11-
* [Test your favorite Flash content](#test-your-favorite-flash-content)
12-
* [Improve documentation](#improve-documentation)
13-
* [Fix interesting issues](#fix-interesting-issues)
14-
* [Implement missing Flash functionality](#implement-missing-flash-functionality)
15-
* [Reporting Bugs](#reporting-bugs)
16-
* [Debugging ActionScript Content](#debugging-actionscript-content)
17-
* [Code Guidelines](#code-guidelines)
18-
* [Commit Message Guidelines](#commit-message-guidelines)
19-
* [Pull Requests](#pull-requests)
9+
* [Getting Started](#getting-started)
10+
* [Ways to Contribute](#ways-to-contribute)
11+
* [Test your favorite Flash content](#test-your-favorite-flash-content)
12+
* [Improve documentation](#improve-documentation)
13+
* [Fix interesting issues](#fix-interesting-issues)
14+
* [Implement missing Flash functionality](#implement-missing-flash-functionality)
15+
* [Debugging ActionScript Content](#debugging-actionscript-content)
16+
* [Reporting Bugs](#reporting-bugs)
17+
* [Code Guidelines](#code-guidelines)
18+
* [Test Guidelines](#test-guidelines)
19+
* [Commit Message Guidelines](#commit-message-guidelines)
20+
* [Pull Requests](#pull-requests)
2021

2122
## Getting Started
2223

2324
The [Ruffle wiki](https://github.com/ruffle-rs/ruffle/wiki) is a great way to familiarize yourself with the project. It contains info on how to build Ruffle, using Ruffle, and links to helpful documentation about the Flash format.
2425

25-
Feel free to ask questions in our [Discord server](https://discord.gg/J8hgCQN).
26+
Feel free to ask questions in our [Discord server](https://discord.gg/ruffle).
2627

2728
## Ways to Contribute
2829

@@ -44,63 +45,66 @@ For documentation in the code, we follow the [rustdoc](https://doc.rust-lang.org
4445

4546
Try your hand at fixing [issues that are interesting to you](https://github.com/ruffle-rs/ruffle/issues). Follow the instructions on [building Ruffle](https://github.com/ruffle-rs/ruffle/wiki/Building-Ruffle), familiarize yourself with the [project layout](https://github.com/ruffle-rs/ruffle/wiki/Project-Layout), and use [SWF resources and decompilers](https://github.com/ruffle-rs/ruffle/wiki/Helpful-Resources) to help debug the issue.
4647

47-
You can also ask for mentoring on our [Discord server](https://discord.gg/J8hgCQN).
48+
You can also ask for mentoring on our [Discord server](https://discord.gg/ruffle).
4849

4950
### Implement missing Flash functionality
5051

5152
Ruffle is a young project, and there is still much Flash functionality that is unimplemented. Check for the ["unimplemented"](https://github.com/ruffle-rs/ruffle/issues?q=is%3Aissue+is%3Aopen+label%3Aunimplemented) in issues.
5253

5354
## Debugging ActionScript Content
5455

55-
If you build Ruffle with `--features avm_debug` and enable debug logging (`RUST_LOG="warn,ruffle_core=debug,avm_trace=trace"`) then you will
56+
If you build Ruffle with `--features avm_debug` and enable debug logging with `RUST_LOG="warn,ruffle_core=debug,avm_trace=trace"` then you will
5657
activate a few built-in debugging utilities inside Ruffle, listed below.
5758

5859
### Warnings and Errors
60+
5961
All AVM errors and warnings will print their stack trace so that you can view where they are in relation to the
6062
ActionScript inside the movie. This requires no extra configuration and will be visible by default.
6163

6264
### Trace statements
65+
6366
With `avm_trace=trace`, `trace()` statements will print to stderr.
6467

6568
### Step-By-Step Output
66-
If you use the hotkey `CTRL + ALT + D` you will toggle verbose AVM debugging output on and off (default off).
69+
70+
The hotkey <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>D</kbd> toggles verbose AVM debugging output on and off (default off).
6771
You will be able to follow the flow of ActionScript inside of a SWF movie, as each action is performed.
6872
Please note that this will likely slow down Ruffle, and it may significantly spam output. Please use sparingly.
6973

7074
When paired with a tool such as [JPEXS](https://github.com/jindrapetrik/jpexs-decompiler), you can compare the ActionScript
71-
you see being executed in Ruffle with the actual ActionScript inside of the game, and attempt to find whatever problem
75+
you see being executed in Ruffle with the actual ActionScript inside of a SWF movie, and attempt to find whatever problem
7276
it is that you're looking for.
7377

7478
### Complete Variable Dumping
75-
The hotkey `CTRL + ALT + V` will dump every variable inside the AVM at the moment you press it.
79+
80+
The hotkey <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>V</kbd> dumps every variable inside the AVM at the moment you press it.
7681
This can be very useful to inspect the internal state of games and see, for example, if a coordinate is NaN, your lives
7782
are negative, or maybe an important object just didn't get initialized.
7883

79-
80-
## Reporting bugs
84+
## Reporting Bugs
8185

8286
[Issue reports and feature requests](https://github.com/ruffle-rs/ruffle/issues) are encouraged, and are a great way to measure our progress!
8387

8488
When filing an issue, if possible, please include:
8589

86-
* A clear description of the problem
87-
* The platform you are testing on (web, desktop, OS)
88-
* A link/attachment to the SWF demonstrating the issue, if possible
89-
* Screenshots if the issue is a visible problem
90-
* Bonus points for including the correct output from the official Flash Player
90+
* A clear description of the problem.
91+
* The platform you are testing on (web, desktop, OS).
92+
* A link/attachment to the SWF demonstrating the issue, if possible.
93+
* Screenshots if the issue is a visible problem.
94+
* Bonus points for including the correct output from the official Flash Player.
9195

9296
These types of focused issues are helpful:
9397

94-
* Tracking issues for specific Flash features (ActionScript 3.0, drawing API, etc.)
95-
* Bug reports for specific content that works but isn't quite right (art not looking correct, etc.)
96-
* Platform-specific issues
97-
* Enhancement requests to improve user experience
98+
* Tracking issues for specific Flash features (ActionScript 3.0, drawing API, etc.)
99+
* Bug reports for specific content that works but isn't quite right (art not looking correct, etc.)
100+
* Platform-specific issues
101+
* Enhancement requests to improve user experience
98102

99103
The project is still in the early stages, so many Flash features are unimplemented and not yet expected to work. Please avoid filing generic issues such as:
100104

101-
* A "this SWF doesn't work at all" report (what about it doesn't work?)
102-
* Duplicate issues for each piece of content using an unimplemented feature
103-
* Asking for dates when a feature will be implemented
105+
* A "this SWF doesn't work at all" report (what about it doesn't work?).
106+
* Duplicate issues for each piece of content using an unimplemented feature.
107+
* Asking for dates when a feature will be implemented.
104108

105109
## Code Guidelines
106110

@@ -131,29 +135,78 @@ Specific warnings and clippy lints can be allowed when appropriate using attribu
131135
#[allow(clippy::float_cmp)]
132136
```
133137

134-
### Test Guidelines
138+
## Test Guidelines
135139

136140
Heavily algorithmic code may benefit from unit tests in Rust: create a module `mod tests` conditionally compiled with `#[cfg(test)]`, and add your tests in there.
137141

138-
Most tests are swf-based, with the swfs stored in `tests/tests/swfs`. They are configured in `tests/tests/regression_tests.rs`.
142+
Most tests are SWF-based, with the SWFs stored in `tests/tests/swfs/`. They are configured in `tests/tests/regression_tests.rs`. To add a new test, create an `.swf` that runs `trace()` statements. You can do this in several ways, listed below.
143+
144+
Once you have an `.swf`, run it in Flash Player and create a file `output.txt` with the contents of the trace statements. Add the `output.txt`, `test.swf` and either the `test.as` or `test.fla` file to a directory under `tests/tests/swfs/avm1` (or `avm2`) named after what your test tests, and add a line in `regression_tests.rs` to have Ruffle run it.
145+
146+
Running `cargo test [your test]` will run the `.swf` in Ruffle and compare the `trace()` output against `output.txt`.
147+
148+
### Flash authoring tool
149+
150+
Create a new ActionScript project. Save the `.fla` file and export an `.swf` (File -> Export -> Export Movie...).
151+
152+
Adobe Flash Professional CS6 is the most recent version to support both ActionScript 2 and 3. Newer versions support ActionScript 3 only.
153+
154+
### Motion-Twin ActionScript 2 Compiler
155+
156+
This is a free and open source command-line ActionScript 2 compiler. It can be downloaded from [here](http://tech.motion-twin.com/mtasc.html#download).
157+
158+
Create a `test.as` file in a text editor, per the following template:
159+
160+
```as
161+
class Test {
162+
static function main() {
163+
// Your test here.
164+
trace("Hello World!");
165+
}
166+
}
167+
```
168+
169+
Then compile it using:
170+
171+
```sh
172+
mtasc -main -header 200:150:30 test.as -swf test.swf
173+
```
174+
175+
### Apache Flex SDK
176+
177+
This is a free and open source SDK capable of compiling ActionScript 3 code. It can be set up as follows:
178+
179+
1. Download a release for your platform from [here](https://flex.apache.org/download-binaries.html), and extract the files somewhere.
180+
2. Add the `<sdk-root>/bin` directory to your `PATH`. After that, the command-line compiler `mxmlc` (among other tools) should be available.
181+
3. `mxmlc` needs a `playerglobal.swc` in order to work, which can be grabbed from [here](https://fpdownload.macromedia.com/get/flashplayer/updaters/32/playerglobal32_0.swc). Place it in `<sdk-root>/frameworks/libs/player/32.0/playerglobal.swc`, while creating intermediate `player` and `32.0` directories.
182+
4. Define the `FLEX_HOME` and `PLAYERGLOBAL_HOME` environment variables to the path of the extracted SDK root, and the path of the `<sdk-root>/frameworks/libs/player` subdirectory, respectively.
183+
5. Edit `<sdk-root>/frameworks/flex-config.xml` and change `<target-player>27.0</target-player>` to `<target-player>32.0</target-player>`.
184+
185+
After `mxmlc` is set up, create a file `test.as` in a text editor, per the following template:
186+
187+
```as
188+
package {
189+
public class Test {}
190+
}
191+
192+
// Your test here.
193+
trace("Hello World!");
194+
```
195+
196+
Then compile it using:
197+
198+
```sh
199+
mxmlc -output test.swf -compiler.debug=true Test.as
200+
```
139201

140-
To add a test here, create a .swf file that runs `trace()` statements. You can do this by:
141-
* creating a .fla file in a Flash authoring tool
142-
* creating a .as file in a text editor, and compiling it using a commandline compilation tool:
143-
* [`mtasc`](http://web.archive.org/web/20210324063628/http://tech.motion-twin.com/mtasc.html) (ActionScript 2 only)
144-
* if you create a file `test.as` with a `class Test` with a `static function main` with the code you want to run, you can compile it using `mtasc -main -header 200:150:30 test.as -swf test.swf`
145-
* [`mxmlc`](https://helpx.adobe.com/air/kb/archived-air-sdk-version.html) (ActionScript 3 only)
146-
* if you create a file `test.as` with a `class Test`, you can compile it using `mxmlc Test.as`. `mxmlc` is located in the `bin` folder of the downloadable AIR SDK.
147-
* you may want to use docker instead -- something like `docker run -it --rm -v ${PWD}:/src jeko/airbuild mxmlc ./Test.as` works well
148-
* [`rabcasm`](https://github.com/CyberShadow/RABCDAsm) (ActionScript 3 only)
149-
* This test allows writing AVM2 bytecode sequences directly, without intermediate AS3 code. This is primarily useful for testing opcodes that aren't generated by the above-mentioned AS3 compilers.
150-
* `rabcasm` cannot generate SWF files from scratch. Instead, you must first generate a SWF from the above mentioned methods, then extract and disassemble its ABC with `abcexport` and `rabcdasm`.
151-
* Once you have modified your bytecode, you must reassemble and inject it into the movie with `rabcasm` and `abcreplace`.
152-
* If you are adding a new test, commit both your SWF source (.fla and/or .as files) as well as the modified bytecode (.abc files and test-0 folder).
202+
You may want to use Docker instead - something like `docker run -it --rm -v ${PWD}:/src jeko/airbuild mxmlc -output test.swf -compiler.debug=true Test.as` works well.
153203

154-
Run the .swf in Flash Player and create a file `output.txt` with the contents of the trace statements. Add the `output.txt`, `test.swf` and either the `test.as` or `test.fla` file to a directory under `tests/tests/swfs/avm1` (or `avm2`) named after what your test tests, and add a line in `regression_tests.rs` to have Ruffle run it.
204+
### RABCDAsm
155205

156-
Running `cargo test [your test]` will run the .swf in Ruffle and check the `trace()` output against `output.txt`.
206+
[RABCDAsm](https://github.com/CyberShadow/RABCDAsm) allows writing AVM2 bytecode sequences directly, without intermediate AS3 code, which is primarily useful for testing opcodes that aren't generated by the above-mentioned AS3 compilers.
207+
However it cannot generate SWF files from scratch. Instead, you must first generate a SWF from the above mentioned methods, then extract and disassemble its ABC with `abcexport` and `rabcdasm`.
208+
Once you have modified your bytecode, you must reassemble and inject it into the movie with `rabcasm` and `abcreplace`.
209+
If you are adding a new test, commit both your SWF source (`.fla` and/or `.as` files) as well as the modified bytecode (`.abc` files and `test-0` folder).
157210

158211
## Commit Message Guidelines
159212

@@ -163,25 +216,26 @@ Here is a sample commit message:
163216
web: Fix incorrect rendering of gradients (close #23)
164217
```
165218

166-
* If applicable, prefix the first line with a tag indicating the relevant area of changes:
167-
* `core:`
168-
* `desktop:`
169-
* `web:`
170-
* `avm1:`
171-
* `docs:`
172-
* `chore:`
173-
* `tests:`
174-
* Capitalize the first letter following the tag
175-
* Limit line length to 72 characters
176-
* Use the present tense and imperative mood ("fix", not "fixed" nor "fixes")
177-
* Reference any PRs or issues in the first line
178-
* Use keywords to close/address issues when applicable ("close #23")
179-
* Write more detailed info on following lines when applicable
219+
* If applicable, prefix the first line with a tag indicating the relevant area of changes:
220+
* `core:`
221+
* `desktop:`
222+
* `web:`
223+
* `avm1:`
224+
* `avm2:`
225+
* `docs:`
226+
* `chore:`
227+
* `tests:`
228+
* Capitalize the first letter following the tag.
229+
* Limit line length to 72 characters.
230+
* Use the present tense and imperative mood ("fix", not "fixed" nor "fixes").
231+
* Reference any PRs or issues in the first line.
232+
* Use keywords to close/address issues when applicable ("close #23").
233+
* Write more detailed info on following lines when applicable.
180234

181235
## Pull Requests
182236

183237
Pull requests are the primary way to contribute code to Ruffle. Pull requests should be made against the latest `master` branch. Your pull request should not contain merges; you should always rebase when bringing the latest changes into your branch from the `master` branch. If there are merge conflicts, or if your commit history is messy, please rebase onto the latest master. [`git rebase -i`](https://thoughtbot.com/blog/git-interactive-rebase-squash-amend-rewriting-history#interactive-rebase) is a great way to clean up your pull request.
184238

185-
When you make a pull request, our [CI](https://circleci.com/gh/ruffle-rs/ruffle) will build your changes and run them through all tests and style checks. All of these tests should pass before your pull request can be accepted.
239+
When you make a pull request, our [CI](https://github.com/ruffle-rs/ruffle/actions) will build your changes and run them through all tests and style checks. All of these tests should pass before your pull request can be accepted.
186240

187241
One of [our regular contributors](https://github.com/orgs/ruffle-rs/people) will review your changes and try their best to helpfully suggest any changes. If all goes well, your PR should be merged without much delay. We use both standard merge commits and fast-forward merges depending on the size of the changes. Thanks for your contribution!

0 commit comments

Comments
 (0)