[Zacam]

This is the consolidation of previous sticky posts to help provide the "One Stop Shopping" sort of starting point for folks.

So, lets begin the journey, shall we?

• Post #2: Reporting Bugs: The HOW-TO
    Details Mantis, our bug reporting system and where it is and how to use it.
    (modified from the original post created by Inquisitor)
• Post #3: Getting the Code: SVN and You
    Takes you through how and where to go to check out the source code.
    (copied from the original post created by Karajorma)
    Sign up for email summaries of all SVN commits by joining the FS2Source Google Group
• Post #4: RE: "Hi, I'd like to code for you, where do I start?"
    Whether you are new or you've been around, the question is "How can I get started with helping or coding for the SCP?", this post will hopefully provide some answers. New original Post by Zacam.
• Post #5: What to do when SCP coders cannot reproduce your fs2_open crashes?
    You've got a bug, you've reported it, but it doesn't seem to want to show itself to a coder. This post will help you out with how you can help us help you.
    (copied from the original post created by Fury)
    You can also call this the "How do I Compile My own FSO Exec?"
• Post #6: How to write new Sexps. A guided tour, by The E.
• Post #7: How to enable multiplayer support for new sexps. A guide by Karajorma.
• Post #8: How to use gdb to get debug information on Linux. In case the guide in post #5 is not usable for you. Written by niffiwan.
• Post #9: How to transfer patches from svn to git

As time progresses, the following posts may change, or new ones added, this post will serve as a changelog for that.

[Zacam]

(modified from the original post created by Inquisitor)

We use a bug-tracking system called Mantis, and it is located here.
This is used to track bug reports only. It's highly recommended that you give a read to Karajormas wonderful article: "How to report bugs - A Coder's Perspective" before starting.
Additionally, give a read to this article on how to submit bugs. It will save both you and us a substantial amount of grief.

Here are the Guidelines to adhere to when using Mantis:

• Look before you leap - make sure there isn't a similar bug before you post a new one. If there is a similar bug, post info on your particular circumstance.
• Give the bug an intelligible title.  Nothing is worse than "it's broke" or "weird problem".  Help us make sense of it.
• Provide as much information as you can.  What you think is unimportant could actually be very important in finding out what's causing the bug.  It's better to have too much than too little.
• ALWAYS post what build you're using.  Usually it will have the date in the file name.  If it's just named something like "fs2_open_r", post where you got it from and what date it was posted.
• ALWAYS post what command lines you're using, and whether removing them makes the problem go away.
• ALWAYS post whether you're using any of the mediaVPs, and whether removing them makes the problem go away.
• ALWAYS run a debug build and post any errors you get with it (Not all builds have a debug build with them though)
• ALWAYS keep track of any bugs you report.  Check them regularly, provide reminders to the coders if necessary, and make sure your Mantis emails aren't getting eaten by the spam filter.  If we can't reproduce your bug, and we can't get in touch with you, we WILL remove your bug report.
• If you haven't done so already, READ THIS ARTICLE.  Seriously.

If you must browse without registering, please use these credentials:

Username: SCPGuest
Password: password

However, note that you will not be able to report bugs as a guest. To be fully involved, please take the time to register. We do not allow anonymous bug reporting: the reason we require registration is so that we can keep in touch with our bug reporters.  Again, bug reporting is not fire-and-forget. We will usually need to ask you to do something to help us fix the bug.

Help us help FreeSpace. You guys are as important to this process as any of the developers.

[Zacam]

(copied from the original post created by Karajorma)

Here's how you set things up:

NOTE: For Windows 7 folks, you may need/want to install hotfix KB982927 first to prevent issues.
(copied from Fury's Guide)

• Go to the Tortoise SVN homepage and download the latest version
• Install it. You'll have to restart your PC afterwards
• Make a new folder on your HD where you'd like to install the code. You'll need a fair bit of space for the code + the intermediate files created when building it.
• Press right mouse in the new folder and choose SVN Checkout from the list.
  
• An new window will open up. Cut and paste this into the URL of repository box svn://svn.icculus.org/fs2open/trunk/fs2_open
• By default the HEAD revision will be selected. You probably don't want to change this. Your screen should now look like this
  
• Press OK to begin downloading from the repository. The process shouldn't take long if you have a reasonably fast connection.

Additionally, for Window Users:
(copied also from Fury's Guide)

• Create a new user environment value where variable name is FS2PATH and variable value is full path to your Freespace 2 folder, by default C:\Games\FreeSpace2. This applies too all Windows OS', not just XP.
• Restart your computer. This step is REQUIRED for the environment variable above to take effect!
• Follow instructions in this guide to optimize TortoiseSVN caching, which reduces disk activity significantly. As per instructions in the linked guide, include your Freespace2 folder and don't forget the asterisk, for example C:\Games\Freespace2\*

[Zacam]

So, you're new here (or maybe you've been around for awhile) and now you want to code, but you don't know what, where or how to get started.

Welcome aboard! And firstly, thanks for taking the time to be here, we hope you will enjoy your stay, and it's my personal hope that you will find the following information useful.

Yes, there is quite a bit of it, no you don't need that tazer, trust me.

Not knowing where to get started with something can be really daunting.
Especially if you've just done a code checkout (for whatever reason) and you're trying to make sense of it all.

Here are some basic bullet points:

• The Cardinal Rule: At the end of the day, the engine MUST be able to load AND use in retail fashion the original Retail FS2 data.
    Everything else added or done to the engine (for a Total Conversion, MOD X or "Just because it's cool") is permitted, but it cannot break that rule.
    This means that any new feature should be turned off by default if it changes retail behavior.
  
• SCP/FSO is Multi-Platform. We operate on Windows, OS X and Linux.
    There are probably quite a few additional platforms, but we're mostly after the 3 Amigo's
    We are probably heaviest on Windows platform coder-wise right now, so more OS X and Linux people are VERY much Welcome
  
• Our Graphics Engine is in OpenGL. We do use GLSL Shaders (currently at a minimum of Shader Model 2.0)
  
• FRED2 is still currently Windows Only, and will not compile on Express editions of MSVC.
    wxFRED is looking to change that, but needs more work to get off the ground.
  
• The Cardinal Rule (Redux): At the end of the day, the engine MUST be able to load AND use in retail fashion the original Retail FS2 data.
    Everything else added or done to the engine (for a Total Conversion, MOD X or "Just because it's cool") is permitted, but it cannot break that rule.
    This means that any new feature should be turned off by default if it changes retail behavior.
  

Don't forget to read the "Getting the Code: SVN and You" post.
As well, ensure you have (at a minimum) a working FreeSpace 2 Install. Anything else after that (TC's, MediaVPs, etc) is completely optional. Recommended install path on Windows is "C:\Games\" or anywhere -OTHER- than "Program Files" or "Program Files (x86)"

What We Are Looking For, Can Use and NEED:

-+People who can Profile/Optimize/Analyze and Debug:
(speaking from MSVC experience here, but there are many tools on other OSes to accomplish this)
Being able to step through Asserts/Warnings/etc and find out how/why and being able to Profile or run Analysis (run-time OR Compiler level) on where the code spends the most of it's time and finding out why.

EVEN IF you are not an excellent or strong coder, don't despair! We still need (what Karajorma affectionately calls) Spaders.
If you can compile the code and run it in a debugger, you can help find (and maybe even fix!) existing issues.
Finding the bugs (and reporting what you found) goes a HUGE mile to helping us improve the engine, especially when some issues can be hard to reproduce. And the best part about it is, again, you don't necessarily need to be a strong coder to do it, and it can provide a GREAT place to start, especially with getting familiar to the state the code is in currently.
(More details here)


-+Resolving Mantis Issues!
We get a lot more New Features or Feature requests worked on than we ever see in resolved Mantis Issues.
Even just a simple "Can this still be reproduced" test and comment on the ticket will go a long way to helping us really know what needs working on.
ALSO: Do check out the FreeSpace & FreeSpace Open Support board on a regular basis. Not to provide support, but to know about User interaction issues and their resolutions.
It's also a great way to see common mistakes and I like to (mentally) resolve issues and see how close I came when the final solution is reached.


Additional Things We Are Looking For:

-+Network Coders:
Aside from taylor/Karajorma, we don't have any.
Multi (and the ability to do really cool things in Multi) is kind of suffering from this. Being able to have stableserver/client connections, SEXPs over Multi, Asteroid/Nebula Online, persistent Multi Campaigns, etc.


-+Graphics API (preferably OpenGL) Coders:
Even DirectX people can help in this area so long as your C/C++ is strong.
Knowing how a graphics API work-flow and pipeline works is what we need, especially if it can be translated well into being usable in OpenGL.


-+Documentation and Standardization:
We're still an intermix of C and C++ and this can get rather interesting at times.
A lot of things can stand to be better outlined so that we can find weak areas, or redundant (unnecessarily so) portions and address them.
As well, being able to follow data from point A all the way to Z (and see what it does along the way) can be made a lot easier with better thread_safe and documented code, especially if we can have reliable "mangers" to handle passing the data around.
(Currently Echelon9 has undertaken being the Point Person for the Documentation Project)


-+People familiar with cross-platform portability issues:
We ESPECIALLY need more dedicated OS X/Linux people.
If you can compile on more than one platform, that is an awesome bonus, but the more people we have in any one platform that can resolve compiler warnings or code issues, the better. Being able to address 64bit expansion would also be nice.


-+Optimizations:
Such as: SSE/SSE2 is done with MSVC at a compiler level, there is nothing run-time wise that takes advantage of of the performance
available by enabling/using these extensions.
This is just one example, I'm sure there are many more places where we can have optimizations.


-+External Transparency:
FRED compiles the same CODE dir as FSO, but it has it's own needs as well as to have the things it can or cannot use explicitly defined with it.
Being able to have the code ONCE and usable multiple times or to multiple places would be the best thing since sliced bread.
The ability to have SEXPs, LUA and accurate external Table/Data parsers that can validate data (outside of either the engine or FRED) can help make modding people happy, and happy modders make more content.


Current Hangups:

Collision Detection: The code spends more time here than anywhere else.

Asteroid Code: It needs better data structures and better algorithms for tossing rocks at ships.

Rendering: Modern graphics cards should be able to render high-detail models much faster than they do in FSO. Smarter understanding/reworking of the rendering code could possibly fix that, and give us some major FPS increases

More Modular Tables: Not everything that is Tabled by Retail currently has modular extendability. This would include being able to use a 'mod.tbl' for settings that are generally mod specific or "Global" settings that don't have a place anywhere else.


Other things that would be nice (aka: Some somewhat more specific examples):

-+Converting/Updating the VP format to allow for Compressed (non-solid) Archives (LINK):
As described in the link, the ability to compress VP files (or distribute them compressed and leave them that way) would be much appreciated as Mods/TC's get larger.


-+Native usage of OpenCollada DAE as an in-game model format.
Failing that, implement and expand the POF format as much as possible.
(Being able to generate and store IN the POF the Cache file, for instance.
Would probably require collaboration with PCS2 to make happen)


-+wxFRED:
Since FRED2 Open is a Windows only application (and will not compile under Express Editions of MSVC), wxFRED's objective is manifest as:

• Replicate all of the existing (or at least, Retail to start) functionality of FRED
• Be available to users on the Big 3: OS X, Linux, Windows. Preferably with a consistent UI
• Where possible, address the short comings of FREDs UI and ease of use, enhance the systems scalability

-+LUA & SEXP Organization and Management:
Sort of ties in with the Transparency noted above, but this is also about making sure that we can have a scalable method for controlling these and adding new ones.


-+Interface Overhaul:
Similar to the HUD Overhaul, this would allow for customization to take place with being able to create, define and layout new Interface elements instead of relying on limited fixed-functionality or specific image formats.
(One idea: An expanded "Advanced" Options screen, possibly in the Pilot Select screen (as the Game State hooks are not set yet) where options currently controlled by the launcher can be set)


-+People to Fulfill or Test feature Requests:
Cause we can get a lot of them. Especially in the public forum. At some point, should you be granted an SCP Badge, you'll find we have an Internal Forum for Hosted Projects Collaboration. These are Feature Requests being made because a MOD/TC is actively finding them necessary to continue their project, so those will get TOP priority.


-+Feedback and Testing on other Projects:
Aside from FSO itself, we have the wxLauncher, a cross-platform Installer, PCS2 and any other number of tools that can use help. Many of the original FS (Descent Manager) Tools haven't seen an update in AGES.


How This Will Work:

Alright, so you've gotten some feedback or you have found something to work on, and you want access or the ability to commit it. And hey, you've probably done an awesome job on it, so why shouldn't you?

Well, we are an at will community. This is our free time, for the largest part. And we've had a lot of in's and outs in our coder base as well as our code base. So, we need to make sure that changes that happen are understandable and maintainable. We can't make anybody stay, but those that are here need to be able to continue maintaining the code. So here is how the process works.

• Find your Feature/Bug that you want to work on and work it, test it, refine it, get it to where you think it's ready for the lime light.
• Generate a .diff or a .patch for your code changes. Create a topic (or respond to an existing one) or the Mantis Issue (we also like seeing Topic Posts for updates to Mantis Issues, so we can be sure they don't get missed) and attach your diff/patch to that.
• An SCP coder (possibly several) will take a look at it. And no, it won't happen automagically. We don't don't have a bat signal or Spidey Sense, it may take us a while, so relax.
• Feedback will take place from whomever grabs and compiles/tests your code. EVEN IF the person responding to you isn't a Coder, some key words to watch for in ANY response is "causing warnings in the compiler" or "getting an error 'X" in testing it". Follow up and own those and resolve them if they happen.
• Stay positive and communicative. Even if you think it should be obvious to everybody, provide clarification when asked for it. We all walk different paths and have different skills, this is what makes us great, but can also cause the greatest discord when we don't communicate well.

Once the code has undergone peer review, it will initially be contributed to our SVN by an SCP coder (with all appropriate credits given). There is no hard and fast "Do 'X' number of things, Get a Badge, do 'Y' more after that, get Write Access". It's all about the quality of the work and the commitment to getting it done, and done well and rightly the first time through.

Code can also be an art as much as it's a science. It's easy to get frustrated. But we're here to help those who -want- to help themselves so that we can all be better. We're open to any idea, but be aware that liking and wanting an Idea done is not the same thing as everybody dropping everything and doing it right then and there. We're not a fast paced, high volume code-fest (though there are times where we have our moments!), so be assured that Patience is not only highly valued, but also well rewarded.

Communications with Coders can take place here, in these forums, or you can hit us up on #SCP channel on Esper.Net IRC. (that's a link to go there using Mibbit, a browser based IRC). And unless other wise suggested by another coder, don't just go PM'ing somebody in regards to something.

[Zacam]

(Note: If you already have gone through the above posts for checking out the code, or already have an established IDE, you can skip to step 25. This guide is meant to be a 'absolute zero' start to finish for people to be able to follow)

(copied from the original post created by Fury)

So you have encountered frequent problems with fs2_open that leads to crashes? You have already provided debug log for support people and coders, but it wasn't enough and no coder can reproduce these crashes to fix the problem? Don't worry, you can help the coders out by providing important information needed to track it down.

This however involves downloading and installing Visual C++ 2013 Express, TortoiseSVN and fs2_open repository. All of this has been instructed in detail below, so be sure to follow them to letter and ask for help when needed. It's not hard at all, but it does require some time and effort.

What you however can't do is track down non-crash related problems. Such problems will require more or less knowledge about the code and coding itself. In addition these instructions cannot be used to solve crashing problems in fred2_open, as fred2_open cannot be compiled in Visual C++ 2010 Express.

1. Download Visual C++ 2013 Express and install it.
2. Check Microsoft Update for software updates.
3. If you use Windows 7, install hotfix KB982927, click the "View and request hotfix downloads" link in top of the page. Or install Service Pack 1. TortoiseSVN is likely to trigger this Windows bug.
4. Download TortoiseSVN and installl it.

5. Create a new user environment value where variable name is FS2PATH and variable value is full path to your Freespace 2 folder, by default C:\Games\FreeSpace2. This applies too all Windows OS', not just XP.
6. Restart your computer. This step is REQUIRED for step 5 to take effect!

7. Follow instructions in this guide to optimize TortoiseSVN caching, which reduces disk activity significantly. As per instructions in the linked guide, include your Freespace2 folder and don't forget the asterisk, for example C:\Games\Freespace2\*

8. Create a new folder to your Freespace2 folder called fs2_open.
NOTE: If you need or want to use antipodes FSO builds instead, then create a folder called fs2_open_antipodes.
9. Right click on the folder and select SVN Checkout.
10. Copy this to "URL of repository": svn://svn.icculus.org/fs2open/trunk/fs2_open
NOTE: If you need or want to use antipodes FSO builds instead, then use following url: svn://svn.icculus.org/fs2open/branches/antipodes
11. Make sure "checkout folder" is the folder you created in step 8. Make sure "checkout depth" is set to "fully recursive". And finally, make sure "HEAD" is selected in "revision". Then click OK.

NOTE: Steps 12-15 are optional steps and should only be done if instructed so by a coder. Skip to step 16 if you're unsure.
12. If you have received a patch-file from a coder, make copy of the folder created in step 8 and call it something like fs2_open_patchname where patchname is name of the patch you've been provided.
13. Place the patch file in fs2_open_patchname folder. Then right-click on the patch file and select TortoiseSVN --> Apply patch.
14. Two windows will open, the smaller window lists files that the patch modifies. Right click on the small window and select "Patch all".
15. If there are no errors of any kind, you can close these windows now. Otherwise, ask the coder who provided your patch for assistance.

16. Go to fs2_open folder (or the copy of it if you followed steps 12-15), open projects\MSVC_2013 folder. From there open file called Freespace2.sln. Select Visual C++ Express 2013 as the application to open it in if asked to choose an application.

17. On left side you see a small window called solution explorer. Right click on "Freespace2" and select Properties.
18. Again on left of the newly opened window you see "common properties" and "configuration properties", under "configuration properties" select "debugging".
19. Change "Command" to: $(FS2PATH)\$(TargetFileName)
20. Click OK.

NOTE: If a coder advises you to do a clean build, you can do this by following steps 16-20. Make sure Visual C++ 2013 Express window is active, press Ctrl + Alt + F7. Then follow instructions from step 21 onwards. If this is your first time doing this, you can safely skip straight to step 21. Even if this is not your first time, normally clean build is not needed.

21. Look up to the toolbar row. Under "Help" you see a green triangle and to right a dropdown menu. Select "Debug Inferno SSE2" from the dropdown menu.
22. Press F7 on your keyboard. A small "Output" window opens. Wait until it finishes, this probably takes a few minutes on most computers.

23. When text in the "Output" window stops rolling, last three lines should be more or less as follows:

Code: [Select]

6>  Freespace2.vcxproj -> C:\Games\FreeSpace2\fs2_open\projects\MSVC_2010\Debug SSE2\fs2_open_3_7_2_SSE2.exe
6>          1 file(s) copied.
========== Build: 6 succeeded, 1 failed, 0 up-to-date, 0 skipped ==========
In third to last line you will see name of the exe file that has been copied to your Freespace2 folder. If a file of same name already existed, it has been overwritten.

In second to last line you will see whether copying has been succeeded or failed, this needs to say succeeded for us to continue. If this says failed, seek assistance on the forums or irc, alternatively browser based irc link.

In the last line you will see outcome of your build. Normally you will see one failed because Visual Studio Express cannot compile fred2_open. This is fine and we can continue. If you have more than one failed, seek assistance on the forums or irc, alternatively browser based irc link.

NOTE: If you need to seek assistance, select the "Output" window and then press Ctrl + A, this selects all text from the window. Now, copy and paste the text to Pastebin and include a link to your pasted text for coders to read.

24. From your Freespace2 folder, open launcher. We need to run FSO in windowed mode, so first lower your resolution from video tab. Then go to features tab, select dev tool from under list type. Select windowed mode. Also ensure other settings such as active mod are suitable for your bug hunting. Click OK.

25. Go back to Visual C++ 2013 Express window and make sure it is active. Press F5.
26. In a moment you will see FSO window opening up. Note that running FSO in this mode is significantly slower than it would be normally, you just have to bear with it.
27. Now play FSO normally until you encounter the crash bug.

NOTE: If you missed something in the launcher, like selected wrong mod or your resolution is too large or too small for windowed use, exit FSO. Change required settings in the launcher, then select window of Visual C++ 2010 Express to activate it. Press F5 again.

28. You have encountered the crash you were looking for. Now, there are two types or crashes. First is straight crash to desktop (CTD) which doesn't produce anything more than regular Windows error message about "this application has closed". Second is an error or assert message given by fs2_open and it gives you two options - OK and Cancel. Click OK.
29. Now regardless of whether you got a CTD or fs2_open error/assert message, you should now have "fs2_open_3_7_2_DEBUG_SSE2.exe has triggered a breakpoint" message in your Visual C++ 2013 Express window. Click Break.
30. You see a small window in lower right corner, it has three tabs - call stack, break point and output. Select call stack.
31. After selecting call stack tab, make sure the small window is active. Press Ctrl + A to select all text, then copy and paste that text to Pastebin.
32. Now you need to give a link to your pastebinned text to a coder, either in the forums or irc, alternatively browser based irc link.
33. Follow instructions a coder may give you to further troubleshoot your crash if it is needed.


NOTE: To repeat these steps at a later date:
- Right click on the folder created in step 8, select SVN Update.
- Once update is done, click OK.
- Continue from either step 12 or 16. Steps 12-15 are optional steps and should only be done if instructed so by a coder. Skip to step 16 if you're unsure.

[The E]

Okay, so, CommanderDJ asked about how to write sexps. Since I was bored, I volunteered to write a short guide. This will be posted on the wiki eventually, but for the moment, I'd like more eyes to look over it. Please point out areas that need clearing up, or parts that need to be added.

==========================================================

Writing a new sexp, a guided tour.

Hello and welcome to FSO coding. This lesson will cover the creation of new sexps.

===FILES YOU NEED TO EDIT===

1. sexp.cpp
2. sexp.h
3. (occasionally) sexp_tree.cpp
4. (also occasionally) sexp_tree.h


Okay, so you have an idea for a new sexp. Here's what you need to do in order to make it work. Note that basic understanding of C++ Syntax is needed and assumed present.

Step 1: Find out if the functionality isn't already covered by an existing sexp. There are a lot of functions already present in the sexp system, if you can use them to do what you want without adding another one, or by modifying an existing one, that's almost certainly preferable to writing a new one.

Step 2: Okay, so you've done step one and have determined that you need to do a completely new sexp. So here's the steps you need to do.
   1. In sexp.h, locate a giant list of #defines starting with "#define OP_PLUS". These are the operator constants, which are used internally to route sexp code around. Each of these defines follows a common pattern, a hex number OR'ed together with a category and (in most cases) the OP_NONCAMPAIGN_FLAG flag. Look around until you find the category where your sexp will fit in (which, in most cases, will be the "change" category), and add your flag at the bottom of the list. The hex number must follow consecutively from the last one used in that category. Then add the Category flag, and the OP_NONCAMPAIGN_FLAG (This flag is used to determine if a given sexp can be used in a campaign file to determine mission progression). If your new sexp should be present only in the campaign room, you need to use OP_CAMPAIGN_ONLY_FLAG here.
   2. In sexp.cpp, locate the Operators[] array. Each sexp has a distinct entry here. The format is { "sexp-name", OPERATOR_CONSTANT, Min number of arguments, Max number of arguments }. The sexp name string is what the sexps will later be saved as in mission files, and the documentation.
   3. In sexp.cpp, locate the function eval_sexp(int cur_node, int referenced_node). This function is called to evaluate sexps at runtime, and basically calls the sexps' evaluation function and then returns a return value. Possible return values are:
      SEXP_TRUE: This means that the sexp has executed successfully. This is the default return for all sexps, even those that do not have usable return values.
      SEXP_FALSE: This is used in sexps that return boolean values.
      SEXP_KNOWN_TRUE and SEXP_KNOWN_FALSE: These should be treated with caution. They should only be used in cases where you are absolutely certain that a given result will stay true or false for the entire mission. Examples are found in the is-destroyed sexp for example, which returns SEXP_KNOWN_FALSE if the ship or wing passed as an argument has departed (warped out). The danger here is that once you return a KNOWN value, the sexp system will stop evaluating that specific expression.
      SEXP_UNKNOWN: This is the default value any given sexp tree node has before evaluation starts.
      SEXP_NAN and SEXP_NAN_FOREVER: Should be returned when an operation is supposed to return a number, but can't for whatever reason. SEXP_NAN_FOREVER acts much like the SEXP_KNOWN return values; using it means that a given operation will always return NAN. As an example, if you use get-object-speed on a departed or destroyed object, it will return SEXP_NAN_FOREVER.
      SEXP_CANT_EVAL: Used when the sexp cannot be evaluated yet for whatever reason. For example, this is returned when is-destroyed is used on a ship that hasn't arrived yet.
   These values can and should be returned from your evaluation function, if necessary. It is here that you should insert a call to your evaluation function, with the current node as an argument.
   4. In sexp.cpp, locate the query_operator_return_type(int op) function. In it, you will find a massive switch statement. This is used to determine what your sexp returns, which is in turn used by the sexp syntax checker to determine if your sexp is placed correctly, and by FRED to determine which sexps are available in a given situation. Possible values are:
      OPR_NULL: This sexp does not return anything
      OPR_BOOL: This sexp returns a boolean value
      OPR_NUMBER: This sexp returns a number
      OPR_POSITIVE: This sexp returns a positive number
   There are a few special return types as well. These are used for type matching (that is, to see if a given sexp is valid at a given point in the expression)
      OPR_AI_GOAL, OPR_STRING, OPR_AMBIGUOUS, OPR_FLEXIBLE_ARGUMENT
   5. In sexp.cpp, locate the query_operator_argument_type(int op, int argnum) function. This is similar to query_operator_return_type(), in that it is used to check sexp syntax. If your sexp has more than one argument, or more than one type of argument, you need to use the argnum variable to determine what you need to return. Possible return values are found in sexp.h, look for the block of OPF_* defines.
   6. In sexp.cpp, locate the get_subcategory(int sexp_id) function. Locate the subcategory where your sexp will fit in best, and add your operator constant to the switch statement there.
   7. In sexp.cpp, locate the Sexp_help[] array. This is where you need to add a short description of your sexp, which will appear in the event editor. Syntax is simply { OPERATOR_CONSTANT, "help text" }. Look at the other entries, and follow the formatting found there.
   
   Okay, so that's the whole setup out of the way. Now we'll have to write the evaluation function.
   Almost all evaluation functions have the current node in the sexp tree as an argument. This is used to retrieve arguments given to the sexp by the FREDer. To retrieve arguments from a node, the following helper functions and macros exist:
      CDR(n): Returns the next branch in the tree
      CAR(n): Returns the root node of the current element
      CTEXT(n): Returns a c-string representation of a text argument.
      eval_num(n): Returns a numeric argument
      is_sexp_true(n): Evaluates boolean arguments. Returns true if the expression is true or KNOWN_TRUE.
      sexp_get_ship_from_node(n): Returns a pointer to the Ship pointer, or NULL if the ship can'T be found in the mission.
      ship_name_lookup(CTEXT(n)): Returns the ships' position in the Ships[] array.
      ship_type_name_lookup(CTEXT(n)): Returns the ship class' position the Ship_info[] array.
      
   
Note that, at this time, this guide does not explain how to set up sexps for multiplayer. Use Karajorma's guide for this

[The E]

For convenience, here's the post about multiplayer sexps:

I got a request from CooperHawkes for an explanation of how you fix a SEXP so that it works in multiplayer so I figured I'd just post the explanation so that the other SCP coders would see how easy it is to fix them.

Firstly you must determine if the SEXP is suitable for fixing. Only the Change SEXPs work with this method. Not every change SEXP needs a fix, only those where the effect is only seen on the server but fails to make it to the client machines.

Fixing a SEXP involves using the Multi_SEXP packet system in order to send the information to the client machines. I coded this in such a way that the coder doesn't need to understand how this works though. All they have to do is call a set of send_x functions on the server and a set of get_x functions on the client. To show how this works I'll convert fade-in to a multi capable SEXP as an example.

Code: [Select]

void sexp_fade_in(int n)
{
float delta_time = 0.0f;

if(n != -1)
delta_time = eval_num(n)/1000.0f;

if(delta_time > 0.0f)
{
Fade_delta_time = delta_time;
Fade_type = FI_FADEIN;
}
else
{
Fade_type = FI_NONE;
gr_create_shader(&Viewer_shader, 0, 0, 0, 0);
}
}
Here's how the SEXP currently looks. From that you can see that the only variable the client machine needs to be aware of is delta_time.

So before the final brace we add the code for the multi call back.

Code: [Select]

// multiplayer callback
multi_start_packet();
multi_send_float(delta_time);
multi_end_packet();
}
The first and last functions say that this is the start and end of a packet of info you want sent to the client machines. Between these you want to include any variables that you need to send to the client machines (including any optional ones the SEXP may have).

And that's it as far as the server is concerned.

Client side you need to add a function that is called when this packet arrives.

Code: [Select]

void multi_sexp_fade_in()
{
float delta_time = 0.0f;

multi_get_float(delta_time);

if(delta_time > 0.0f) {
Fade_delta_time = delta_time;
Fade_type = FI_FADEIN;
}
else {
Fade_type = FI_NONE;
gr_create_shader(&Viewer_shader, 0, 0, 0, 0);
}
}
The majority of the function is a simple copy of the actions carried out in on the host side (for longer SEXPs you should spin that off into a function and call it from both the host and client functions but this one was simple enough to justify a cut and paste instead. )

The function starts with a list of calls to the multi_get_x functions. When dealing with optional arguments you can simply test for

Code: [Select]

if (multi_get_x) as this will return false if the optional argument wasn't present.

The final step is to find void multi_sexp_eval() and add a case for the this particular SEXP pointing back to the function to call (in this case multi_sexp_fade_in() ).

Code: [Select]

case OP_CUTSCENES_FADE_IN:
multi_sexp_fade_in();
break;
And that's it. The code handles everything else internally. So now none of you have any excuse for making SEXPs that don't work in multiplayer.

[niffiwan]

This is basically the same info as post #5, except for Linux with gdb instead of Windows.

gdb is pretty simple, in order to get a stack trace from a FSO crash, do the following in a terminal:

1) install Git and checkout a current copy of the code

2) install gdb

Code: (Debian/Ubuntu & derivatives) [Select]

sudo apt-get install gdb


Code: (Fedora & friends) [Select]

sudo yum install gdb

3) setup your mod & settings using wxLauncher - in addition to your normal settings you must have:

• a smaller-than-your-entire-monitor resolution (Basic Settings)
• "run in a window" (Advanced Settings -> Dev Tool)
• "don't grab mouse/keyboard in a window" (Advanced Settings -> Dev Tool)

If you don't set these three options, then you'll find that you can't leave the FSO window in order to use the debugger.

4) Run the debug version of FSO (if you don't already have it, pass "--enable-debug" as a parameter to autogen.sh and then compile it)

Code: [Select]

gdb fs2_open_3.6.15_DEBUG

4a) You may need to tell gdb where the FSO source code is, specifically the fs2_open/code directory.

Code: [Select]

gdb dir /path/to/fso/source/code
5) gdb has it's own prompt.  Run FSO with this obvious command

Code: [Select]

run
6) Switch to your FSO window and do whatever is necessary to reproduce the crash

7) When the crash has occurred, switch back to your terminal and enter this at the gdb prompt:

Code: [Select]

backtrace
8) copy this output and post it where an SCP member can see it

9) Exit FSO by running this at the gdb prompt:

Code: [Select]

quit

The procedure above is probably all you need. However, if you're interested, here's some more info:

Backtraces
A backtrace (MSVC calls it a stack trace) displays all the function calls that the program has passed through to get to its current position.  Here's an example:

Code: [Select]

(gdb) backtrace
#0  wing_name_lookup (name=0x1993500 "Gamma", ignore_count=1) at ship/ship.cpp:11316
#1  0x00000000005d7dc4 in post_process_mission () at mission/missionparse.cpp:5317
#2  0x00000000005d7b37 in parse_mission (pm=0xfb8120, flags=0) at mission/missionparse.cpp:5270
#3  0x00000000005d8be9 in parse_main (mission_name=0x7fffffffded0 "respawn_crash.fs2", flags=0) at mission/missionparse.cpp:5642
#4  0x00000000005bfd9f in mission_load (filename_ext=0xbfb9c0 "respawn_crash") at mission/missionload.cpp:107
#5  0x000000000040c465 in game_start_mission () at freespace2/freespace.cpp:1450
#6  0x0000000000415e4f in game_enter_state (old_state=20, new_state=52) at freespace2/freespace.cpp:5974
#7  0x00000000004b90fc in gameseq_set_state (new_state=52, override=0) at gamesequence/gamesequence.cpp:282
#8  0x0000000000414ccd in game_process_event (current_state=20, event=1) at freespace2/freespace.cpp:5145
#9  0x00000000004b95f2 in gameseq_process_events () at gamesequence/gamesequence.cpp:397
#10 0x0000000000417605 in game_main (cmdline=0x227edd0 "") at freespace2/freespace.cpp:7092
#11 0x00000000004177da in main (argc=1, argv=0x7fffffffe308) at freespace2/freespace.cpp:7226
(gdb)
The backtrace shows all the function names and the values of variables passed to those functions, e.g. on line 6 above (game_enter_state), you can see that variable old_state was 20, and variable new_state was 52.

Viewing variables
You can view the current value of variables using the gdb print command e.g.

Code: [Select]

print Ship_info[0].name
This can also be used to display nearly any C/C++ expression.

Breakpoints
Breakpoints are a way of stopping FSO from running at a certain point in the code. Set one by entering the following at the gdb prompt:

Code: [Select]

break freespace2/freespace.cpp:1758
The format is directory/filename:line-number (obviously the source code you're getting the file & line number from must match the executable your running, otherwise this information may not match)

Debugging with an FSO release executable
In the rare occasion when you cannot reproduce the crash in FSO debug you can also get a backtrace from the release version.  Use the same procedure as above, but keep in mind these caveats:
1) you must recompile the executable with the gcc -g option set (i.e. CXXFLAGS=-g make)
2) debugging may not be 100% reliable because the release version uses various compiler optimistaions (i.e. gcc -O2)

To workaround both these issues, compile like this and run gdb with the resulting executable:

Code: [Select]

make distclean && CXXFLAGS='-g -O0' sh autogen.sh && V=1 make

(The V=1 is not strictly neccessary, but it does show you if the CXXFLAGS were picked up correctly)

Debugging with a GUI
The command line is all well and good, but sometimes a GUI really helps and ddd is what I've used (the package name should be "ddd" to install with apt-get or yum).  It's very similar to gdb (and in fact, runs gdb underneath) but you get two obvious extras, a window to display variables/data at all times, and an interactive display of the source code (where, among other things, you can set break points via right-clicking on the appropriate line of code).

Other GUI's include:

• cgdb: TUI based
• nemiver: gnome oriented, vaguely in the style of visual studio
• qtCreator: a complete IDE, but can be used for standalone debugging, my current favourite

[The E]

(The following was copied from this thread)


Yesterday, Karajorma had a bit of a problem. His work on sexp container classes was locked up in a patch file against the last revision of our SVN, and none of the solutions we found for converting an svn patch into a git patch actually worked (If you know how to do this, please mention it!).

I then volunteered to convert the stuff to git manually. Kara then asked me to document the process I used so that others may learn from it.

So, basically, here's the workflow I used.

• Create a new branch in git based off of the last revision of the svn. In git, this is represented by this commit.
• Apply the svn patch to a clean checkout of the svn repo.
• Copy all files changed by that patch into the git checkout.
• Commit the changes made through this.
• Merge the newly created branch with the current master in the git repo.
• Resolve any merge errors.
• Try to compile, fix any compilation errors. In this case, errors were caused by Kara's use of SCP_hash_map, a container that has since been deprecated and replaced with SCP_unordered_map.
• Commit any changes made.

And that's it.