Howto:Start core development: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
Line 151: Line 151:


Also, if you have some new ideas in mind, and would like to extend FlightGear in some way, it's a good idea to use the issue tracker to make feature requests. Fellow FlightGear developers will be able to provide feedback regarding your feature request and tell you directly if and how exactly your idea can be best implemented.
Also, if you have some new ideas in mind, and would like to extend FlightGear in some way, it's a good idea to use the issue tracker to make feature requests. Fellow FlightGear developers will be able to provide feedback regarding your feature request and tell you directly if and how exactly your idea can be best implemented.
For example, to view a list of feature requests that were accepted by other core developers, just go to: https://code.google.com/p/flightgear-bugs/issues/list?can=2&q=FeatureRequest%20status%3Aaccepted


= Talking to fellow FlightGear developers =
= Talking to fellow FlightGear developers =

Revision as of 18:11, 11 November 2012

This article is a stub. You can help the wiki by expanding it.

01/2012: I have taken my forum response and copied/pasted it here. Everybody is invited to contribute. While we do have a Volunteer page, we don't currently have a page dedicated to people wanting to contribute to the C++ source code, so this is an attempt to get something like this started.

How the Project works (Suggested reading!)

Please see this short essay here: http://flightgear.org/forums/viewtopic.php?f=42&t=15267#p149971

Welcome to FlightGear

Hi, and welcome to FlightGear!

You have probably come here to learn more about implementing new features for FlightGear.

Often, implementing new ideas and features doesn't necessarily require C++ knowledge, FlightGear has become so flexible and powerful that it is increasingly configurable even without touching the C++ source code. This is an important advantage, because building FG from source and finding your away around two fairly complex code bases (i.e. SimGear and FlightGear) can be a daunting task, even for experienced C++ developers.

This isn't to say that C++ / programming knowledge wouldn't be useful though. And if that's where your interests are, you are certainly invited to contribute to the C++ code, too.

Not yet familiar with C++ ?

If you don't yet know what a compiler is, what C++ is or how programming works, you may want to check out Howto: Understand the FlightGear development process.

While learning how to program is definitely possible, learning C++ in particular and becoming familiar with a complex code base like FG/SG does take a certain amount of time. In particular, setting up a working build environment to build FG from source, can be a daunting task for people without any corresponding background knowledge.

If you know for sure, that you want to learn C++, we have a collection of helpful resources here: C++ resources. This includes a bunch of animated screen casts (i.e. video tutorials) on youtube: http://www.youtube.com/view_play_list?p=1D6727247CA35794

Developing without programming is possible and appreciated

For non coding-related ideas on how to to start contributing, there's a dedicated article here: http://wiki.flightgear.org/Volunteer

Also, creating new aircraft, cockpits, scenery, instruments, GUI dialogs etc doesn't require any programming knowledge at all.

If that's what you are interested in, please check out: (developer portal links)

Coding but not in C++ (scripting)

If you are definitely interested in coding, but not in building FlightGear from source (C++), you may want to look into Nasal programming instead, which is FlightGear's built in scripting language, and doesn't require anything besides FlightGear itself.

Many new ideas or features won't require any modifications to the C++ source code at all. You could probably get started and implement many ideas without even touching an IDE or a compiler for quite a while.

That might actually be the easiest route for you to proceed in the beginning. Programming knowledge would obviously still be useful, because Nasal scripting is "real programming", many programming concepts (loops, functions, classes, events etc) you'll encounter in Nasal will seem familiar to people with previous programming experience.

The "Nasal" programming language built into FG is syntactically very close to C and C++, it looks a lot like JavaScript - so you could run your own code inside FG without having to build FG from source, no need for compilers or an IDE. FlightGear IS the run time environment for Nasal code.

If you are looking for immediate results, Nasal is probably the most promising route - simply because you don't need to look into all the tedious, non-coding related issues.

For example, the tutorial system built into FG is entirely implemented in scripting space, and fully XML-configurable: Tutorials

This means that you can create/modify and improve tutorials just by editing plain text files with any conventional text editor.

There are many more things possible using Nasal, just see the wiki.

And if you find something not being possible in scripting space, you could either fire up your IDE and extend the interpreter or ask another contributor to provide a corresponding patch.

Shader programming

If you are not interested in C++ programming, but also not in Nasal scripting, there's another option: GLSL Shader programming. FlightGear has an extremely powerful "effects" framework and support for running GLSL shaders. While programming shaders for FlightGear doesn't by default require being a C++ developer, being able to build FG from source and knowing C++ can be really helpful though, especially in order to expose new properties to shaders (i.e. improving the property tree <-> shader interface).

Hacking the C++ code

From now on, this article will provide the required pointers to get you started hacking the FlightGear source code. Ideally, you already know C++, or a language very close to it, like C or Java. Also, you should preferably already have experience building programs from source code, otherwise this may seem pretty frustrating if you do this for the first time, simply because FlightGear has meanwhile become a fairly complex code base with many dependencies that need to be satisfied and built in a certain order.

Initial advice

Our advice would be: Start small, start simple, communicate a lot

  • if you know you want to contribute to the source code, make sure that you are actually able to build FG from source, you can get help using the forum, the mailing list, the issue tracker or live support using IRC chat
  • read the documentation (wiki, $FG_ROOT/Docs)
  • start making tiny modifications to existing stuff (aircraft, scenery, source code etc)
  • try to get to grips with how git works (we have some resources to get you started, using GUI frontends like qgit or a good IDE can be helpful)
  • register an account at gitorious
  • clone the FG project (SimGear, FlightGear, fgdata)
  • browse the issue tracker for bug reports/feature requests, help triage problems, maybe provide patches too?
  • search the archives (forum and mailing list) for discussions related to your area of interest, these contain often valuable pointers that may save you hours of work
  • subscribe to the developers mailing list
  • ask for advice/projects there
  • check out the wiki for ideas to get started (Watch out, there are plenty of "ideas" listed here, but not all of them are up to date or even "good" ideas, so talk to fellow contributors first before spending any significant amounts of time implementing something)
  • coordinate your effort with others, i.e. communicate your intentions early and ask for advice
  • release early and often
  • don't get frustrated :-)
  • enjoy!

Project architecture

FlightGear itself consists of a number of different projects and dependencies (libraries), please refer to gitorious for details. Most of FlightGear's supporting code is increasingly getting moved to the "SimGear" project.

Basically, FlightGear depends on SimGear, while SimGear depends on some 3rd party libraries such as OpenSceneGraph, plib, OpenAL and others.

Once you have satisfied all dependencies and built them in the right order, you can start FlightGear. Note however that FlightGear also has a run time dependency: its so called "base package", i.e. the data package that contains all resources such as scenery, GUI files, aircraft, sounds and so on. We commonly refer to this as "$FG_ROOT".

The FG source tree is commonly referred to as $FG_SRC, while the SimGear source tree is often referred to as $SG_SRC.


The source code

FlightGear is multi-platform software, that runs on all major versions of MS Windows, Mac OS and Linux. That means, the FlightGear source code also needs to be written and maintained with cross-platform considerations in mind.

The core FlightGear source code itself is largely written in C++, some C and a bunch of helper scripts. FlightGear is based on OpenGL (NOT DirectX !), OSG (OpenSceneGraph) and OpenAL (for sound). An increasing number of features are implemented in scripting space, using a high level scripting language called Nasal, Nasal scripts are maintained in the base package ($FG_ROOT).

The SimGear and FlightGear source trees both make use of the CMake build system as of 2012.

The FlightGear project uses the decentralized source code management system "git" see Git for more info.

The project sources are hosted at gitorious: http://gitorious.org/fg/

If you know for sure that you'd like to fiddle with the core source code, you'll inevitably need to be able build FG from source, this is also documented in our wiki, a more recent article is to be found here: http://wiki.flightgear.org/Howto:_Build_FlightGear_with_NetBeans_using_CMake

You can find tutorials for different platforms/OS at the end of the article.

Continuous Integration (CI)

For CI purposes, there's a dedicated build server running which rebuilds the FlightGear sources for a handful of important platforms. The server provides a simple and quick overview, it can be found here: http://flightgear.simpits.org:8080/

Please see FlightGear Build Server for more information.

Patches

Regarding patches, please see: Submitting Patches.

Note that this article is meanwhile somewhat depreciated and these days using gitorious (and filing merge requests there) is pretty much encouraged. If your patch is related to a previously reported bug/defect, you can obviously also use the issue tracker (see below).

In general, the FlightGear gitorious project is the entry point for new developers: http://gitorious.org/fg/

Some more recommendations can be found at Recommended Project Policies.

In general, it is always a good idea to clone the FG repositories (i.e. SimGear, FlightGear and FGData) and start working on your own branch there. This will enable fellow contributors to easily keep track of your work, so that they can test your changes and provide feedback as required.

To send patches upstream, gitorious merge requests are recommended. The details of which are covered at Merge request.

Ongoing efforts

A list of the latest development efforts can be found at http://wiki.flightgear.org/Category:Core_development_projects If you have anything to add, please feel free to create a new wiki article. Also, contributing such news to the FlightGear newsletter is another good idea.

If you are looking for ideas to get involved one way or another, some of the more long-term issues and most annoying glitches are discussed at Request for comments.

However, please take everything you'll find there with a grain of salt, because many of these articles haven't been updated over the years, so what may have seemed like a great idea 2-3 years ago, may already be depreciated meanwhile. On the other hand, those articles may still help you get a better understanding of architectural issues.

Also, there's another outdated category titled "Code Cleanup": http://wiki.flightgear.org/Category:Code_Cleanup

Another option would be taking a look at the "Google Summer of Code" category which also lists project ideas collected over the years: GSoC: Candidate Projects. We also have a separate sub forum for GSoC here: http://flightgear.org/forums/viewforum.php?f=38

In other words: pick your poison :)

Issue tracking

Ideas (feature requests actually) and bug reports are ideally reported using the issue tracker here: http://flightgear-bugs.googlecode.com/

Please make sure to first search the issue tracker before possibly reporting a dupe, thanks!

This is also an excellent place to get started helping and contributing to FG, i.e. by triaging bug reports, discussing feature requests, posting patches or finding new ideas to work on. This is also a very good place to get in touch with other core developers.

Also, if you have some new ideas in mind, and would like to extend FlightGear in some way, it's a good idea to use the issue tracker to make feature requests. Fellow FlightGear developers will be able to provide feedback regarding your feature request and tell you directly if and how exactly your idea can be best implemented.

For example, to view a list of feature requests that were accepted by other core developers, just go to: https://code.google.com/p/flightgear-bugs/issues/list?can=2&q=FeatureRequest%20status%3Aaccepted

Talking to fellow FlightGear developers

Most core development related discussions are handled using the developers mailing list: http://www.flightgear.org/mail.html

There's a fully searchable archive available here: http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/

In addition, the FlightGear forums are increasingly used for interesting development related discussions, please note though that these are usually not specific to FG core development, but instead general development (aircraft, scenery, shaders, scripting): http://flightgear.org/forums/

If there's something particular that you are interested in, it's always a good idea to search these resources (wiki, forum, mailing list) to find related discussions.

Flight dynamics

Improving the flight dynamics often doesn't require any C++ changes, FlightGear provides a powerful FDM interface and different FDM engines (namely JSBSim and YaSim), both of which are entirely configurable by using XML files.

For JSBSim, please see: http://jsbsim.sourceforge.net/

Important docs

There's a wealth of documentation to get you started available in $FG_ROOT/Docs


Even more documentation can be found in our wiki, here: http://wiki.flightgear.org/

The wiki is divided into different "portals", you'll probably be interested in the developers portal here: http://wiki.flightgear.org/Portal:Developer

You are obviously invited to start your own wiki articles, in order to document your projects or help improving existing documentation. Also, some core developers actually use the wiki to post their own development roadmaps. For example, see: Plan-zakalawe or Project Rembrandt.

FlightGear

Don't worry if your C++ experience should be dated: In many parts, the FlightGear code base is still somewhat archaic and not very modern, so you won't find too many occurrences of really advanced C++ concepts, in many places you'll just find simple "C with classes" uses, some STL and inheritance. But complex C++ features (such as advanced templates or meta-programming are not too common actually).

One of the simplest ways to add new features to FlightGear is adding new commands to it, so called "fgcommands" (i.e. "FlightGear commands"). For additional information, please see this tutorial: Howto: Add new fgcommands to FlightGear.

Programming resources

If you need to read up on something programming related, such as C++, the STL, OpenGL, shaders etc, the wiki has plenty of programming resources to get you started: Resources.

SimGear

The SimGear code base is somewhat less archaic and more modern actually. And if you are interested in contributing to the OpenGL/SceneGraph department, you'll inevitably need to look into OpenSceneGraph (OSG), too - which really is "modern C++".

SimGear is fairly well-maintained code base that contains a fair amount of doxygen comments, that means that it's easy to create doxygen documentation for SimGear. For example, see: http://simgear.sourceforge.net/doxygen/

Note that, at the time of reading, this may be outdated, so if you are interested in using the latest doxygen docs, you are well advised to run doxygen against your own latest simgear clone.

Also, you can get a fair amount of information out of the FG sources by running them through doxygen, too.

Plain C ? (Nasal)

If your C++ is rusty and you'd just like to get started quickly, there are also certain FG components that are strictly (largely) pure C, the Nasal interpreter is just one example (Nasal is FlightGear's built in scripting language): http://wiki.flightgear.org/Nasal_scripting_language

The Nasal interpreter is part of the SimGear project, and can be found in $SG_SRC/nasal: http://gitorious.org/fg/simgear/trees/next/simgear/nasal

Adding new extension functions to the built-in Nasal interpreter is documented here: Howto: Extend Nasal.

There's also a separate wiki article providing a list of known issues related to the Nasal interpreter itself: Improving Nasal.

None of this requires any C++ knowledge!

Only the scripting interface connecting the Nasal interpreter and FlightGear is implemented in C++, it can be found in $FG_SRC/Scripting: http://gitorious.org/fg/flightgear/trees/next/src/Scripting

Basically, the scripting interface implements a custom SGSubsystem, so that the Nasal interpreter can be run as a FlightGear system. In addition, all FlightGear-specific extension functions are to be found there. Increasingly, this folder also contains wrappers to map FlightGear classes to Nasal space in an OOP fashion, so that not just functions, but full "objects" are provided, which are computed lazily. If that's what you are interested in, you should take a look at the NasalPositioned.cxx source code, which demonstrates how this is done.

In other words, even without knowing C++, you can contribute to FlightGear core by extending the Nasal system. If you have some specific project in mind, you could probably implement it largely in scripting space using Nasal and only augment it as required with new extension functions in C space.

Getting started

Once you have found an area you are interested in, you can search the wiki, archives (mailing list and forums) or the issue tracker to find suitable projects to work on, for example: http://code.google.com/p/flightgear-bugs/issues/list?can=2&q=nasal&colspec=ID+Type+Status+Priority+Summary+Aircraft+Milestone&cells=tiles

Talk about your plans

Before you start any serious efforts, please make sure to get in touch with other contributors. Ideally, using the developers mailing list or the forum. This is to ensure that others know about your plans, i.e. to avoid duplicate work, but also conflicting approaches.

Often, FlightGear developers have certain ideas and plans for their projects, so it's good to coordinate your ideas with fellow contributors. In addition, you can get valuable feedback from experienced contributors this way, which may save you countless hours of time and lots of frustration.

You may even find people interested in your idea and teaming up with you!

Adding new subsystems

If you are interested in adding new subsystems to FG, you may want to check out this: Howto:Create new subsystems.

Also, we have a step-by-step guide illustrating how a new system can be added to FlightGear, going into more detail. See Howto:Create a 2D drawing API for FlightGear

The property tree

The FlightGear property tree is documented here: Howto:Work with the Property Tree API

Finally

...please don't get discouraged if you shouldn't get too much feedback in the beginning, probably many contributors are busy preparing the next release: http://wiki.flightgear.org/Release_plan

Lack of feedback doesn't necessarily mean that nobody likes your project or your ideas, probably it just means that you need to do some networking to get in touch with other contributors.

Usually, getting involved in the forum, the issue tracker or in merge request discussions via gitorious is a good idea to familiarize yourself with the project. Please keep in mind that we get to see plenty of people each month announcing some fancy new FlightGear-related projects, so your signal/noise ratio is pretty important here. It's pretty likely that the type of feedback you get will be improving once you start contributing patches and help triage bug reports.

People announcing that they want to work on FlightGear, without knowing C/C++ or without having ever built software from source, obviously have to face a steep learning curve, and we are aware of that.

Sometimes, it may even take good ideas a while to be recognized as such, even if suggested by seasoned long-term contributors. So, please don't interpret lack of feedback as a general lack of interest.