Adding sourcefile to the codebase

Discussion about the project in general, organization, website, or any other details that aren't directly about the game.
Post Reply
Message
Author
User avatar
mem359
Dyson Forest
Posts: 214
Joined: Sun Jun 08, 2014 1:18 am

Adding sourcefile to the codebase

#1 Post by mem359 »

I was trying a PR for what seemed like a simple code change, when I got in a lot of trouble since I didn't know how to properly add a new file to the code base. I figured it might help to list some questions in the forum (as my PR already has a lot of comments about needed corrections).

I found the wiki page for adding and removing source files from the codebase, but it is woefully short on details.
  1. I only have Mac OSX (Xcode). Do not have Linux or Windows.
    Will I be able to modify the files needed to compile on those platforms with a text editor?
    Or will the lack of Visual Studio (Windows) require me to ask one of the mods to handle the PR?

    (If the answer is "yes I can edit", then I'll post a follow-up with questions about MSVC.)
  2. Is there a listing of all the target builds, and maybe a description?

    In Xcode, I see: Configure, GG, Parse, Common, ClientCommon, FreeOrionServer, FreeOrionClient, FreeOrionAI, FreeOrion, and MakeDMG.
    The Wiki page suggests only putting files into the appropriate projects, but I'm largely in the dark about the projects.
    (How is ClientCommon different than FreeOrionClient or FreeOrionAI?)
  3. I was recently told "when building the file as part of freeorioncommon the symbol needs to be exported with FO_COMMON_API". (My function probably shouldn't be in Common, but I'm still curious about this.) Are there "rules" somewhere for this kind of thing? I noticed FO_COMMON_API all over the code base, but this is the first time I've heard someone talk about it.

    (I tried searching for that term in the forum and the wiki, without success. Seems like the search engine brought up everything with "common", but no hits for the API.)

dbenage-cx
Programmer
Posts: 389
Joined: Sun Feb 14, 2016 12:08 am

Re: Adding sourcefile to the codebase

#2 Post by dbenage-cx »

Thanks for working on consolidating these to one function.
mem359 wrote:Will I be able to modify the files needed to compile on those platforms with a text editor?
I think XCode is the only one requiring some specific editor (the rest of us have to rely on others for such additions).
For MSVC, might search through msvc2015/ for mentions of some similar file (possibly Directories.h and Directories.cpp).
CMake files are not bound to any specific editor.
Is there a listing of all the target builds, and maybe a description?
Kind of wish the cpp api had a chart for targets, but that might need to be manually maintained.
Possibly be some slight differences between cmake/msvc/xcode:
  • Human client (aka freeorion)
  • AI client (aka freeorionca)
  • Server (aka freeoriond)
  • Common library
  • Parse library
  • GiGI library
  • GiGi SDL library
Configure and MakeDMG looks to be xcode specific: probably akin to or calling cmake/make_versioncpp.py and XCode/make_dmg.py
I hesitate to add descriptions as I don't want to spread misinformation, though Common is code seemingly utilized in Parse and all 3 executables.

LGM-Doyle
Programmer
Posts: 219
Joined: Mon Feb 29, 2016 8:37 pm

Re: Adding sourcefile to the codebase

#3 Post by LGM-Doyle »

Hello mem359.

First, getting started in a new project is always difficult and requires reading a lot of code. Trust the code, not the documentation. If you can compile and run the code, then you know it is working. The documentation, may never have been correct and you and the dev who wrote the documentation may have a different understanding of the words. The code is interpreted by the compiler so it means exactly that same thing to you, the other devs and the compiler.

Now to your questions.

1. All of the project files are just text files. The cmake files are well documented. The Xcode and MSVC file formats are less well documented, but read the files it may be clear how they work. Otherwise, you will have to search online.

2. When it says to add the files to the appropriate project, it means the following. When you create a new file it needs to be added as a source somewhere so that it will compile into a new object file. Then that object file needs to be linked to all targets that need it.

3. Again trust the code and learn how to search within it using your code editor or IDE of choice.

I don't know how Xcode allows you to search for symbols etc in the the code, but I know that OSX has grep. So from within the freeorion project typing

Code: Select all

grep -r -a1 'define.*FO_COMMON' *
results in

Code: Select all

util/Export.h-#if FREEORION_BUILD_COMMON && __GNUC__
util/Export.h:#   define FO_COMMON_API __attribute__((__visibility__("default")))
util/Export.h-#else
util/Export.h:#   define FO_COMMON_API
util/Export.h-#endif
Then you will have to search for

Code: Select all

 __attribute__((__visibility__("default")))
which will explain that it is a way to limit the visibility of symbols in the object file to improve link and load times.

User avatar
mem359
Dyson Forest
Posts: 214
Joined: Sun Jun 08, 2014 1:18 am

Re: Adding sourcefile to the codebase

#4 Post by mem359 »

Thanks for the feedback.
LGM-Doyle wrote:The Xcode and MSVC file formats are less well documented, but read the files it may be clear how they work. Otherwise, you will have to search online.
I asked in case an online search would have been in vain. :mrgreen:

I was mostly concerned about the vcxproj.filter files.
There is a "UniqueIdentifier" (32 hex digits) for each of the folder areas. If that was just some number, fine. If it is some kind of checksum, then adding a file (for the include or compile Item groups) might break that.

User avatar
Vezzra
Release Manager, Design
Posts: 6095
Joined: Wed Nov 16, 2011 12:56 pm
Location: Sol III

Re: Adding sourcefile to the codebase

#5 Post by Vezzra »

I advise against editing the Xcode and MSVC project files manually with a text editor. If you add a source file to the project, making the necessary changes to the cmake files is fine and even required, but if you don't have Xcode and/or MSVC please request the necessary changes to them to be made by a dev who has a MSVC/Xcode FO development environment set up. If you create your PRs with the option enabled that devs with push access to the FO repo can also push to your PR (which it is by default), then one of us can easily push the required changes to your PR.

Post Reply