SVN: Difference between revisions
Executables update: pay attention to added/removed shaders |
|||
(One intermediate revision by the same user not shown) | |||
Line 1: | Line 1: | ||
== So what is this SVN thingy then? == | == So what is this SVN thingy then? == | ||
SVN stands for '''S'''ub'''V'''ersio'''N'''. It's a framework originally developed for | SVN stands for '''S'''ub'''V'''ersio'''N'''. It's a framework originally developed for coding projects, often with multiple programmers working on the code at the same time. | ||
The Dark Mod is a project distributed over the whole world, that's where SVN comes in handy. It allows all Team Members to work on the Mod at the same time without coming in the way of each other. | The Dark Mod is a project distributed over the whole world, that's where SVN comes in handy. It allows all Team Members to work on the Mod at the same time without coming in the way of each other. | ||
Line 9: | Line 9: | ||
[[Image:Svn layout.png|500px]] | [[Image:Svn layout.png|500px]] | ||
Basically, we have one central SVN server run by | Basically, we have one central SVN server run by taaaki. It is accessible for all Team Members, Contributors and Beta Mappers. | ||
Everybody runs his or her own copy of the mod repository on his local hard drive and the SVN Client Software ( | Everybody runs his or her own copy of the mod repository on his local hard drive and the SVN Client Software (recommended TortoiseSVN) provides some convenient functions to keep the copies in sync with each other. | ||
Looking at the graph, you'll notice several repositories, each serving a specific purpose: | Looking at the graph, you'll notice several repositories, each serving a specific purpose: | ||
* '''darkmod''': This is the mod itself. It contains all files needed to run the Mod | * '''darkmod''': This is the mod itself. It contains all files needed to run the Mod. This includes the compiled code, the textures, the entity and material definitions, skins, models and whatnot. | ||
* '''darkmod_src''': The coder's realm. This is where our C++ sources are kept. From the files in this repository, the code | * '''darkmod_src''': The coder's realm. This is where our C++ sources are kept. From the files in this repository, the code gets compiled into executables, which are uploaded to the '''darkmod''' repository in regular intervals. | ||
* '''darkmod_hires''': This is meant to be a backup repository for losslessly compressed texture files. As the main mod diffuse textures are stored in DDS format (a lossy compression format), we want to keep a backup of these files in TGA file format (see also [[How to add Textures to The Dark Mod]]). | * '''darkmod_hires''': This is meant to be a backup repository for losslessly compressed texture files. As the main mod diffuse textures are stored in DDS format (a lossy compression format), we want to keep a backup of these files in TGA file format (see also [[How to add Textures to The Dark Mod]]). | ||
* '''texture_src''': The place for texture source/working files, like Photoshop .psd files, Gimp files - everything including layers. | * '''texture_src''': The place for texture source/working files, like Photoshop .psd files, Gimp files - everything including layers. | ||
Line 45: | Line 45: | ||
The SVN terminology can be confusing at times, this is a (probably incomplete) list of terms explained: '''[[SVN Glossary]]''' | The SVN terminology can be confusing at times, this is a (probably incomplete) list of terms explained: '''[[SVN Glossary]]''' | ||
== SVN | == Filename conventions == | ||
While modern technologies can often handle weird characters in filenames, not every piece of software does it well. | |||
This is serious: during 2.09 beta, the whole release branch had to be recreated from scratch because some filename had spaces! | |||
For this reason, please limit the set of characters used in filenames to the following: | |||
* English letters of any case: a-z, A-Z | |||
* Digits: 0-9 | |||
* Underscore: _ | |||
* Hyphen/minus: <tt>-</tt> | |||
Use only one dot '<tt>.</tt>' to delimit name from extension. | |||
Start filename with a letter. | |||
== Executables update == | |||
Sometimes the C++ code from '''darkmod_src''' repository is built into executables, which are committed to '''darkmod''' repository, so that developers without compiler could test the new version. | |||
Such an "executables update" can be done at any time by any developer. | |||
If you decide to do it yourself, please follow these rules: | |||
* Make sure svnversion works properly. Build TDM, run it, open game console: you should see the '''nonzero''' SVN revision number in the lower-right corner. More details here: [[The Dark Mod - Compilation Guide#Working in SVN]]. | |||
* Do '''not''' commit 32-bit executables. [https://forums.thedarkmod.com/index.php?/topic/20398-notice-32-bit-executables-deprecated/ They are deprecated], so better don't fill repository with useless trash, which would remain there forever and ever... and ever =) | |||
* Do '''not''' commit Typeinfo executables, they are useless. If you really want the dirty details, see [[TypeInfo and Memory debugging configuration]]. | |||
* Make sure you build '''Release''' configuration. Debug executables are not only slow, but also much larger than release ones, so committing them irreversibly eats space on the SVN server. | |||
* Commit executables update as a separate commit, do '''not''' mix it with any other changes like scripts, textures, defs, whatever. In the first line of commit message, mention revision number of '''darkmod_src''' you are building from. | |||
* Ideally, you should commit all updates at once: Windows and Linux 64-bit executables and shaders update. If you don't have access to some OS, you can omit its executable from commit. Or ask someone else to do the update, maybe even wait for the release manager to update them for the next development build. | |||
Regarding the last point. | |||
When you build TDM from source code on any OS, two things happen: | |||
# Executable is put into <tt>../darkmod/</tt> directory. | |||
# Shaders are copied from <tt>glprogs/*</tt> into <tt>../darkmod/glprogs/*</tt>. | |||
Since shaders are usually tied to C++ source code, both executables and shaders must be committed at once, otherwise they will be incompatible with each other. | |||
So if you decide to commit executables, commit shaders too, and vice versa. Make sure both are compiled/copied over recent and clean SVN state. | |||
Pay attention to added and removed shader files: the easiest way to handle them is to delete <tt>glprogs</tt> from the assets repo before building, and add all unversioned files there after building. | |||
{{tutorial-SVN}} | {{tutorial-SVN}} |
Latest revision as of 07:55, 16 May 2021
So what is this SVN thingy then?
SVN stands for SubVersioN. It's a framework originally developed for coding projects, often with multiple programmers working on the code at the same time.
The Dark Mod is a project distributed over the whole world, that's where SVN comes in handy. It allows all Team Members to work on the Mod at the same time without coming in the way of each other.
DarkMod SVN Infrastructure
The graph below shows The Dark Mod's SVN infrastructure:
Basically, we have one central SVN server run by taaaki. It is accessible for all Team Members, Contributors and Beta Mappers.
Everybody runs his or her own copy of the mod repository on his local hard drive and the SVN Client Software (recommended TortoiseSVN) provides some convenient functions to keep the copies in sync with each other.
Looking at the graph, you'll notice several repositories, each serving a specific purpose:
- darkmod: This is the mod itself. It contains all files needed to run the Mod. This includes the compiled code, the textures, the entity and material definitions, skins, models and whatnot.
- darkmod_src: The coder's realm. This is where our C++ sources are kept. From the files in this repository, the code gets compiled into executables, which are uploaded to the darkmod repository in regular intervals.
- darkmod_hires: This is meant to be a backup repository for losslessly compressed texture files. As the main mod diffuse textures are stored in DDS format (a lossy compression format), we want to keep a backup of these files in TGA file format (see also How to add Textures to The Dark Mod).
- texture_src: The place for texture source/working files, like Photoshop .psd files, Gimp files - everything including layers.
- model_src: The repository for Blender, Lightwave, MotionBuilder, Maya, 3DSMax source files, everything needed to re-export models and animations from scratch.
- sound_src: The location where all sound project files or WAV files can be stored.
- betamapper: This is a separate repository for our beta mappers and contributors. They are encouraged to upload their files (maps, textures, models, etc.) to this repository (each mapper can have his/her own folder). This way they can take advantage of SVN's versioning system and also have a nice backup of their work.
What are those red and green icons for?
TortoiseSVN has a nice feature showing you the current state of the files in your working copy:
The most common ones will be green, red and blue:
- green stands for normal, not locally modified by you. No changes waiting for commit. The file might have been changed on the server, though.
- red (exclamation mark) means that the file/folder has been modified by you. The change is waiting to be committed to the SVN server.
- red (x symbol) means that the file is marked for deletion. It will be deleted on the SVN Server the next time you commit.
- blue means that the file has been marked for addition. It will be uploaded to SVN the next time you commit.
- yellow indicates a conflict (usually after an SVN Update).
You lost me there, I need an example!
All right then, here you go:
- Downloading The Dark Mod
- How to commit changes to SVN
- How to add files to SVN
- How to delete files from SVN
- How to resolve SVN conflicts
SVN Glossary
The SVN terminology can be confusing at times, this is a (probably incomplete) list of terms explained: SVN Glossary
Filename conventions
While modern technologies can often handle weird characters in filenames, not every piece of software does it well. This is serious: during 2.09 beta, the whole release branch had to be recreated from scratch because some filename had spaces!
For this reason, please limit the set of characters used in filenames to the following:
- English letters of any case: a-z, A-Z
- Digits: 0-9
- Underscore: _
- Hyphen/minus: -
Use only one dot '.' to delimit name from extension. Start filename with a letter.
Executables update
Sometimes the C++ code from darkmod_src repository is built into executables, which are committed to darkmod repository, so that developers without compiler could test the new version.
Such an "executables update" can be done at any time by any developer. If you decide to do it yourself, please follow these rules:
- Make sure svnversion works properly. Build TDM, run it, open game console: you should see the nonzero SVN revision number in the lower-right corner. More details here: The Dark Mod - Compilation Guide#Working in SVN.
- Do not commit 32-bit executables. They are deprecated, so better don't fill repository with useless trash, which would remain there forever and ever... and ever =)
- Do not commit Typeinfo executables, they are useless. If you really want the dirty details, see TypeInfo and Memory debugging configuration.
- Make sure you build Release configuration. Debug executables are not only slow, but also much larger than release ones, so committing them irreversibly eats space on the SVN server.
- Commit executables update as a separate commit, do not mix it with any other changes like scripts, textures, defs, whatever. In the first line of commit message, mention revision number of darkmod_src you are building from.
- Ideally, you should commit all updates at once: Windows and Linux 64-bit executables and shaders update. If you don't have access to some OS, you can omit its executable from commit. Or ask someone else to do the update, maybe even wait for the release manager to update them for the next development build.
Regarding the last point. When you build TDM from source code on any OS, two things happen:
- Executable is put into ../darkmod/ directory.
- Shaders are copied from glprogs/* into ../darkmod/glprogs/*.
Since shaders are usually tied to C++ source code, both executables and shaders must be committed at once, otherwise they will be incompatible with each other. So if you decide to commit executables, commit shaders too, and vice versa. Make sure both are compiled/copied over recent and clean SVN state. Pay attention to added and removed shader files: the easiest way to handle them is to delete glprogs from the assets repo before building, and add all unversioned files there after building.