TrustedUser
2,147
edits
Difference between revisions of "Developer Central"
First draft of a 'Where do I start with the code base?' section
(→Getting started: Add link to bug tracker) |
(First draft of a 'Where do I start with the code base?' section) |
||
| Line 4: | Line 4: | ||
* The first thing you need to be able to do is [[Git#Retrieving_the_code|get the ScummVM code]] from our [[Git]] repository. | * The first thing you need to be able to do is [[Git#Retrieving_the_code|get the ScummVM code]] from our [[Git]] repository. | ||
* Then you should [[Compiling ScummVM|compile ScummVM]]. | * Then you should [[Compiling ScummVM|compile ScummVM]]. | ||
* If you are new to open source, you can also try reading https://opensource.guide/how-to-contribute/ | |||
* Then read [[#Help! Where do I start with the code base?|Help! Where do I start with the code base?]] | |||
That was easy, right? Here are some more tips: | That was easy, right? Here are some more tips: | ||
| Line 18: | Line 20: | ||
* Our [http://doxygen.scummvm.org/ Doxygen source code documentation] may help you to get the big picture about ScummVM. | * Our [http://doxygen.scummvm.org/ Doxygen source code documentation] may help you to get the big picture about ScummVM. | ||
* Also, you might want to check our list for current [[Platform Limitations]]. | * Also, you might want to check our list for current [[Platform Limitations]]. | ||
== Help! Where do I start with the code base? == | |||
=== Code base structure === | |||
The ScummVM code base is quite big, but well structured with five main components: | |||
{| class="wikitable" | |||
! style="text-align:left;"|Component | |||
! Source code location | |||
|- | |||
| The OSystem API, which defines available features a game can use, such a drawing on screen or receiving keyboard and mouse events. | |||
|common/system.h | |||
|- | |||
|The backends, which implement the OSystem API for various platforms. | |||
|backends/ | |||
|- | |||
|The game engines. | |||
|engines/ | |||
|- | |||
|Common code, that provides various utility classes (for example containers) and audio, image, and video codecs that game engines can use. | |||
|common/<br>audio//<br>image/<br>video/ | |||
|- | |||
|Gui code, that provides a graphical user interface for the game launcher and options dialog. | |||
|gui/ | |||
|} | |||
And then you have a few more directories: | |||
* base/ | |||
: This is the entry point for the application. It for example handles command line argument parsing and the main loop. See [[#Entry points|Entry points]] below. | |||
*test/ | |||
: Contains unit tests for some utility classes from the common code. | |||
* po/ | |||
: Contains translation of the ScummVM GUI into various languages | |||
=== First steps === | |||
The OSystem API shields game engines and gui code from the actual platform the software is running on. The backends code is the only part of the code base that is platform dependent. So if you want to work on a game engine for example you will need to look at the OSystem API to know what you can do in the engine, but you can ignore everything in the backends code as you don't need to know how the OSystem API is actually implemented. On the other hand if you wand to port ScummVM to a new platform, the backends code is what you will want to look at. | |||
You can start by browsing a bit the source code to see how it maps to the description above, and then depending on your interests select one piece of code to look at in more details. For example if you are interested in ports, look at how one specific port is implemented. Or if you are interested in game engines, look at one engine. | |||
In you are interested in game engines, the <code>plumber</code> engine is the simplest one by far, and you can start from there to see the overall structure of an engine. Then you can select an engine for one of the free games we have on our [https://www.scummvm.org/games/ download page] (for example [https://www.scummvm.org/games/#queen Flight of the Amazon Queen], with the corresponding engine source code in <code>engines/queen/</code>), or a game you already own. You can make changes and see how it behaves, run the engine with a debugger, and use an hexadecimal editor to look at the game data file and map them to what the engine does. At first you can in particular look at the engine's use of the classes in the common/ folder, such as Common::File, Common::Array. Start getting a feel for what classes are available before you move onto the graphic and event handling stuff. | |||
If you interest lies with ports and how ScummVM interacts with various operating systems, take a look at the source code in <code>backends/</code>. There are two main categories of backends: monolithique ones and modular ones. The modular backends split the OSystem API implementation between several modules, the GraphicsManager being maybe the most important. Most modular backends use the [https://www.libsdl.org SDL library] and share some code between them. | |||
Our [http://doxygen.scummvm.org doxygen documentation] might help to grasp class hierarchy and navigate the source code at first. In particular it provides a visual representation of the relationship between classes. Using an IDE such as Visual Studio, Xcode, Eclipse, QtCreator or CLion can also be a big help. See the create_project tool to generate projects for various IDE. | |||
Once you are no longer completely lost and have a grasp of the code base structure, a good way to dive deeper might be to find a task to work on. You can have a look at the [https://bugs.scummvm.org bug tracker] and the various TODO lists on this wiki. See the [[Developer_Central#Projects, plans, things to do|Projects, plans, things to do]] section. Once you have a sense of something concrete you want to work on, you are highly encourage to visit our IRC channel (#scummvm on freenode) where you can ask for helps and guidance from fellow developers. | |||
=== Entry points === | |||
# The executable entry point varies depending on the platforms (and therefore it is in <code>backends/</code>). For example for Linux you will find it in <code>backends/platform/sdl/posix/posix-main.cpp</code> while for macOS it is in <code>backends/platform/sdl/macosx/macosx-main.cpp</code>. | |||
# From there it goes into the actual ScummVM main entry point, <code>scummvm_main()</code> implemented in <code>base/main.cpp</code>. | |||
# It alternates between showing the Game Launcher and running a game. | |||
## While the GUI is running (in the game launcher or options dialog) the main loop is <code>GuiManager::runLoop()</code> in <code>gui/gui-manager.cpp</code>. | |||
## Each game engine has its own entry point, which is its implementation of the pure virtual <code>Engine::run()</code> function. | |||
== Pull Request approval process == | == Pull Request approval process == | ||