Skip to content

Latest commit

 

History

History
136 lines (106 loc) · 7.4 KB

CONTRIBUTING.md

File metadata and controls

136 lines (106 loc) · 7.4 KB
Raw

How to contribute

Bug reports, feature requests and pull requests are always welcome.

If you encounter any bugs or want to request a new feature (for example, new function implementations), please head over to the issue tracker and create a new report.

If you want to implement new functionality or fix bugs yourself, you are more than welcome to do so! Below is a brief guide of what needs to be done when creating a pull request for FRESteamWorks. If you encounter any issues along the way or have any questions, feel free to contact me by either sending an email to the address listed in my profile, or by opening an issue in the issue tracker.

Modifying and building FRESteamWorks

FRESteamWorks mainly consists of four parts:

  • the AS3 library side (lib/ folder)
  • the AIR native extension (src/FRESteamWorks/)
  • the Linux API wrapper binary (src/APIWrapper/)
  • a small test application (test/) along with associated build scripts

Each non-trivial pull request that can be tested from the ActionScript side should be accompanied by testcases in the test application (test/src/FRESteamWorksTest.as). Thus, when adding new functionality to FRESteamWorks that is meant to be used from the AS3 side, you would have to modify all four parts of FRESteamWorks.

Here's a quick step-by-step guide on how to add new functions to FRESteamWorks - if you're fixing a bug, some of these steps may be skipped. Whenever you're making any changes to the code, please try to stick as closely as possible to the prevalent coding style of the file you're modifying.

  1. Get the necessary prerequisites. Fork the repository, clone your fork (make sure to initialise the submodules with git submodule update --init) and create a new branch for your changes. For more details on how to do this, see the Github Help article.

  2. Set up a config file (config.sh (Linux + OS X) or config.bat, see the corresponding config_example.{sh,bat} file for a template).

  3. To add new functions to FRESteamWorks, you'll first have to convert the function signature of the Steamworks API function you want to implement to AS3 and add that signature to lib/API.txt (which contains the signatures of all already implemented functions). This includes converting all native types to the corresponding AS3 types, as well as deciding on a return value for the function - which usually mirrors the return value of the Steamworks function. If the Steamworks function returns void, your AS3 function should still return a bool (indicating a successful dispatch of the API call). The name of your function should usually mirror the Steamworks API function name, with the exception of starting with a lowercase letter.

  4. After adding the new function signature, open a terminal/console, change into the lib/ directory and run ruby ./generateAPI.rb. This will automatically create the AS3 implementations (which generally only forward the call to the native extension/binary) of all functions in lib/API.txt.

  5. Since the AS3 implementations of the library differ on Windows/OS X and Linux, there are two source trees in lib/. Thus, if you need to add any new AS3 classes for your function implementations (e.g. new result objects or constants), these need to be added to both lib/src/ and lib/src_linux/. However, to avoid duplication, the actual source files should be created only in lib/src/com/amanitadesign/steam/ and only a symbolic link should be placed in lib/src_linux/com/amanitadesign/steam/.

  6. Implement the native side of your new function by adding a definition of AIRSteam_YourFunction (if your AS3 function is called yourFunction) to src/FRESteamWorks/FRESteamWorks.cpp, src/APIWrapper/APIFunctions.cpp and src/APIWrapper/APIFunctions.h. The AIR native extension and the Linux API wrapper share a common backend (src/CSteam/CSteam.*) that is used as a thin wrapper around the Steamworks API. Any code that would be shared by both the wrapper binary and the native extension should therefore be abstracted into the CSteam class. This class also takes care of setting up and handling any callbacks. Thus, the native extension/API wrapper functions should only take care of handling the function arguments and forward the call to the CSteam instance.

  7. To build your modified version of FRESteamWorks, open src/FRESteamWorks.sln in Visual Studio on Windows, or src/FRESteamWorks.xcodeproj in XCode on OS X and build the project. This will also take care of creating a new ANE with your changes included inside the lib/bin/ folder. On Linux, you will have to change into the src/ directory in a terminal and run make to create the APIWrapper binary, then manually build the SWC library by changing into lib/bin/ and running ./compileLinuxSWC.sh.

  8. Add tests for your new function to the test application (test/src/FRESteamWorksTest.as). To build the test application, you can use the build scripts in test/bin-debug/ (build.sh on OS X, buildLinux.sh on Linux and build.bat on Windows). To run the application, use the corresponding run script. Make sure that you didn't skip step 7, so that you're actually compiling the test application against the correct ANE/SWC.

  9. If everything is working as expected, add your changes to a commit, push that to your fork and create a pull request. I'll review the changes as quickly as possible and give you feedback, or merge the pull request if everything is ok.

Prerequisites

These are the prerequisites you need to build FRESteamWorks yourself.

General

To regenerate the AS3 implementation of the API, you need a Ruby installation. All Ruby versions >= 1.9 should work. On OS X, Ruby is already pre-installed, on Linux, you can most likely install it from your distribution's repositories, whereas on Windows you have to manually download it (see e.g. ruby-lang.org on how to do this).

To generate the ANE, the Adobe AIR SDK is required. This can be downloaded from the official Adobe website.

Compiling the AS3 side of the library, as well as the test application requires an ActionScript 3 compiler. This can be either mxmlc/compc from the Adobe Flex SDK (which can be downloaded from Adobe's Flex SDK website), or amxmlc/acompc from the Adobe AIR SDK & Compiler. Thus, if you downloaded an AIR SDK version that already includes a compiler, you don't need the Flex SDK.

Lastly, you need a somewhat recent copy of the Steamworks SDK.

Windows

Compiling the Windows native library of the AIR extension requires Visual Studio. Any version of Visual Studio 2010 or later (including Express) should work.

OS X

To compile the native library on OS X, you'll have to install either Xcode or the Xcode command line utilities (which can be installed with xcode-select --install).

Linux

For the API wrapper binary, you need a C++ compiler with C++11 support (g++ >= 4.6 from the GNU compiler collection and clang++ >= 3.1 have been tested) as well as make (only GNU make has been tested so far). These should all be installable from your distribution's repositories. For example, on Ubuntu these can be installed by running sudo apt-get install build-essential in a terminal.