diff --git a/contributing.md b/contributing.md index aa0ed4f..5761720 100644 --- a/contributing.md +++ b/contributing.md @@ -72,15 +72,13 @@ summary after a moment (you'll probably see the message `default.xbe` should now be visible in the file listing for the project. Double click it to open it in the CodeBrowser. The window that opens is where you'll do all your in-situ analysis, should you choose to do so. You'll be -asked whether you want to run analyzers, which is strongly recommended unless -you're certain you won't be using Ghidra for anything else. If you do run the -analyzers, simply clicking "Analyze" in the analysis options window without -changing anything is fine, and the analysis will probably take a couple -minutes. +asked whether you want to run analyzers; say yes. Afterwards, simply clicking +"Analyze" in the analysis options window without changing anything is fine, and +the analysis will probably take a couple minutes. Now we'll import symbols from the JSRF decompilation repository. After running -or skipping the analysis, open the script manager (`Window > Script Manager`) -and select the "Data" folder in the left pane. Double click the script titled +the analysis, open the script manager (`Window > Script Manager`) and select +the "Data" folder in the left pane. Double click the script titled `ImportSymbolsScript.py`, and a file picker will open after a moment. Select `symboltable.tsv` from the `delink/` directory of your cloned JSRF decompilation repository, and you should see a bunch of `Created function...` @@ -130,8 +128,44 @@ listing the contents of the recompiled object file. If the right pane displays an error like "program not found," the Visual C++ 7.0 compiler probably wasn't correctly set up on your `PATH`. +One important piece of information, to make sure you get the correct match +percentages: set `Diff Options > Function relocation diffs` to "None." +Otherwise, approximately all references to functions and non-local variables +will be marked as nonmatching (this has to do with the delinking process not +applying name mangling, which isn't expected to be fixed). + ### Using objdiff +The basic idea of objdiff is to match up the contents of an object file +compiled from our own decompiled code to the contents of an object file +extracted from the game. To that end, functions have to be matched up between +them. In the best case, corresponding functions in each file will have the +same name and be in the same section, at which point objdiff can link them +automatically. Otherwise, one has two click on one of the corresponding +functions in one pane and the other function in the other pane to tell objdiff +to link them. Common cases of this are class methods (the names won't match) +and implicitly generated functions, such as exception handling code placed in +`.text$x` in the recompiled object file. + +Clicking on a function that's been linked across both object files shows a diff +of the disassembly of both versions of the function, with any differences +highlighted. The task at hand is to modify the function in the corresponding +source file such that the match percentage reaches 100%. Depending on how you +configure objdiff, it will rebuild automatically whenever you save a change to +a source file, or you can manually rebuild with the "Build" button at the top +of the right pane. + +There are no hard instructions to give for writing decompiled code. Use +Ghidra's decompilation of the function in the CodeBrowser as a starting point, +and exercise whatever C++ and x86 assembly knowledge you have. Exception +handling code in particular can appear in unexpected places (around `new` +statements, in constructors) and has unambiguous but nonobvious signs in the +disassembly, so it might be worth +[reading](https://www.openrce.org/articles/full_view/21) +[up](https://www.openrce.org/articles/full_view/23) +[on](https://web.archive.org/web/20101007110629/http://www.microsoft.com/msj/0197/exception/exception.aspx) +how they're implemented to learn to recognize them in disassembly and recreate +them in C++ code. ## Contrbuting to Delinking