Использование Source Control с Source SDK

This page needs to be translated.
This page either contains information that is only partially or incorrectly translated, or there isn't a translation yet.
If this page cannot be translated for some reason, or is left untranslated for an extended period of time after this notice is posted, the page should be requested to be deleted.
Also, please make sure the article tries to comply with the alternate languages guide.

В этой статье описывается как использовать контроль исходного кода с Source SDK. Его необходимо использовать даже если вы работаете в одиночку, т.к. он в большой степени автоматизирует процесс слияния обновленного кода, выпущенного через Steam. Без контроля исходного кода каждое такое обновление доставит вам массу хлопот.

В этой статье обсуждается ситема Perforce, которая используется компанией Valve. Эта система бесплатна, если кол-во её пользователей не превышает двух человек. Команды, содержащие большее кол-во человек, могут использовать полностью бесплатные альтернативные продукты, вроде Subversion, но и для них эта статья окажется полезной: все системы контроля версий работают примерно одним и тем же образом. Для пользователей Subversion доступно отдельное руководство(en).

Примечание переводчика: для subversion есть замечательная программная оболочка TortoiseSVN, которую можно скачать здесь. TortoiseSVN поддерживает русский язык (снизу на странице закачки), и имеет русское руководство, что поможет лучше разобраться с контролем исходного на первых парах.

Прежде чем мы начнём

Если вы уже начали программировать без контроля исходного кода, то ОСТАНОВИТЕСЬ!. Контроль исходного кода необходимо начать использовать как можно раньше, поскольку после того как выходит новое обновление для Steam старые версии SDK-кода становятся недоступными.

Если вы хотите применить недавно вышедшее обновление SDK с помощью Perforce к вашему "неконтролируемому" коду, то уже слишком поздно и вам придётся вносить изменения трудным способом. Такие утилиты как Beyond Compare могут облегчить этот процесс, а если после внесения изменений вы последуете рекомендациям, изложенным в этой статье, то это будет последний раз, когда вам придётся это делать.

Где достать Perforce

Прежде всего вам необходимо где-то загрузить Perforce. Загрузите первые два пакета с этой страницы:

• Perforce Server Windows Installer
• P4V Installer

Не загружайте ‘P4Win Installer’ - это устаревшее приложение. Избегайте собственноручной найстройки сетевых параметров во время установки, если только вы действительно не планируете подключаться через локальную сеть или интернет.

Perforce предоставляет собственную документацию, с которой вы можете ознакомиться вместо этой статьи. Эта статья предоставляет более узкоспециализированную информацию.

Совет:Если вы сделали ошибку и хотите перезапустить базу данных Perforce, то запустите это из командной строки: p4 obliterate –y //depot/.... НЕ делайте этого с базой данных, которая уже установленна и работает!

sv

Обзор

Теперь установим свежую копию SDK-кода, с помощью мастера создания модификаций(en) и передадим его в Perforce, который его подцепит. Затем мы создадим ‘ветвление’ (дубликат) этого подчиненного кода в другом каталоге.

С помощью этого ответвленного кода вы будете создавать свою модификацию, изредка обновляя копию, подцепленную Perforce'ом, если вам надо будет сделать резервную копию. Первый экземпляр кода будет оставаться в неприкосновенности до тех пор, пока не выйдет обновление SDK-кода; тогда вы установите это обновление в него прежде чем интегрировать его в ваш ответвленный код. Так как Perforce знает какие файлы изменены, он будет отличным помощником в этом процессе.

Настройка контроля исходного кода

SDK-код Valve станет ‘стволом’ вашей кодовой базы, от которого будет ‘ветвиться’ код вашего мода. Создайте его с помощью мастера создания мода(en). Ваша пользовательская папка будет неплохим местом для его хранения, особенно если вы используете Windows Vista, но поместите его в подпапку, созданную специально для SDK-кода - другая папка, содержащая код вашего мода, будет создана позже.

Совет:Так как вы не будете производить много изменений над вашим стволовым кодом, неплохой идеей станет его архивация. Вы можете использовать окно задания свойств папки чтобы отключить индексацию и включить архивацию. Или еще лучше заархивируйте эту папку в один архив после того как закончите читать это руководство.

Создание рабочего пространства

Теперь начнём работу с Perforce. Запустите P4V - графический клиент. Вас будет приветствовать диалог “Open Connection”.

Если вы не хотите подключаться через сеть, то можете проигнорировать все опции этого диалога, кроме опции 3, которая определяет к какому рабочему пространству вы присоединитесь. Нажмите кнопку ‘new’ справа и назовите рабочее пространство, например, valvesrc.

Рабочие пространства это локальные копии файлов с сервера Perforce. После того как вы закончите у вас будет одно пространство для стволового кода и одно для кода ответвления. И любой, кто будет с вами работать, будет иметь такие же рабочие пространства у себя.

Названия большенства полей диалога рабочего пространства говорят сами за себя, и вам необходимо обратить внимание только на два из них: Root и View. Параметр Root должен указывать на папку, в которую вы только что установили немодифицированный SDK-код, тогда как View указывает на локацию, в которой код будет храниться на сервере Perforce (‘depot’).

Для параметра View используется специальный синтаксис. Часть до пробела определяет виртуальный диск, к которому будет присоединено рабочее пространство, а часть после него определяет подпапки на этом диске. Таким образом вы можете создавать независимые рабочие пространства или объединять зависимые.

Для наших целей необходимо одно независимое. Используйте следующее значение параметра View:

//depot/valvesrc/... //valvesrc/...

Нужно сделать: Допустимо ли использовать просто //depot/... а затем подпапки?

Затем нажмите OK.

Утверждение стволового исходного кода

Теперь у нас есть рабочее пространство с базовым SDK-кодом Valve, но сервер Perforce до сих пор пуст. Нам надо передать наши файлы туда. Для этого мы будем использовать интерфейс Perforce, который должен быть перед вами.

Совет:Вы также можете прочитать про интерфейс в справке Perforce, выбрав Help > Getting Started with P4V.

1. Хранилище/Рабочее пространство (левая панель). Щелкните на вкладке внизу чтобы переключить вид. Рабочее пространство (Workspace) - это ваша локальная копия, а хранилище (depot) - это главная копия, хранящаяся на сервере.
2. Вкладки задач (правая панель). Вкладки, находящиеся внизу этой панели позволяют выполнять любые операции с клиентом Perforce. Мы будем использовать вкладки Pending, Workspaces и Branches.
3. Log (журнал). Ошибки выделяются жирным шрифтом.
4. Главное меню. Большенство опций, представленных здесь, имеют дубликаты в других местах интерфейса, но иногда бывает полезно иметь их под рукой.

Откройте вкладку рабочих пространств (workspace) и вы сможете выгрузить исходный код. Это делается в два шага:

1. Отметьтьте добавляемые файлы. Нам надо добавить всё, так что выберите корень рабочего пространства, для чего щелкните правой кнопкой мыши на корне и выберите ‘Mark for Add’ (отметить для добавления); рядом с этим пунктом находится рисунок с файлом и знаком ‘+’ около него. В SDK много файлов, т.ч. понадобится много времени чтобы скопировать их все. Когда операция добавления закончится, файлы в рабочем пространстве поменяют свой вид, что означает, что они подверглись контролю версий.
2. Утвердите изменения. Откройте вкладку ‘Pending’ (направленная вверх красная стрелка) и вы увидите пункт, называемый ‘default’, который содержит все файлы, которые вы недавно добавили. Подтвердите их с помощью двойного щелчка (или нажатием Ctrl+S). Вам необходимо будет ввести описание изменений.

После того как вы закончите вам будет доступен просмотр нового заполненного вида хранилища. Примите поздравления!

Создание и выполнение ответвления

Ответвление - это то рабочее пространство, с которым вы будете работать. Оно начинается как и любое другое рабочее пространство, но в этот раз вы можете вызвать его после вашего мода и указать ему корень того места, где вы хотите хранить файлы, над которыми вы работаете. Поле View должно быть на его собственном виртуальном сервере, так что используйте что-то вроде этого:

//depot/mymod/... //mymod/...

Если вы уже сделали какие-то изменения, которые вы желаете сохранить, и вы не желаете менять папки, то переместите ваш код куда-нибудь ещё до тех пор пока операция создания ответвления не закончена. Нельзя правильно создать рабочее пространство в папке, которая уже заполнена.

Выберите File > New > Branch Specification... и вы создадите новое ответвление. Дайте ему желаемое имя, вроде valve_to_<mymod>, а затем задайте значение поля View:

//depot/valvesrc/... //depot/mymod/...

Щелкните OK и ветвление будет создано: теперь нам необходимо лишь запустить его. Активируйте рабочее пространство вашего мода (используйте выпадающий список сверху над левой панелью, в котором сейчас выбрано valvesrc), выберите его корень, перейдите к вкладке задач ‘Branches’ и выберите пункт контекстного меню ‘Integrate Using’ вашего нового ответвления. Далее либо снимите флажок ‘Limit integration to’ либо поменяйте значение View на ‘target’. Затем щелкните Integrate.

Мы создали ответвление //depot/valvesrc/ в рабочем пространстве кода. Не забудте чго всё ещё нужно утвердить на сервере Perforce. Сделайте это также как мы делали это для стволового кода ранее.

Проверка (Check Out)

Это сложность, которая будет полезна только если вы работаете с командой программистов. К сожалению вам придётся иметь с этим дело даже если вы работаете в одиночку! Логика такова: все файлы, находящиеся под контролем версий на вашем компьютере, доступны только для чтения если только они не отмечены сервером. Это предотвращает ситуации, когда несколько человек работают над одним кодом одновременно, что ведет к появлению лишней работы и общей путанице.

К счастью проверка (Check Out) проводится очень просто. Если вы работаете в одиночку, то вы можете выбрать самый верхний уровень рабочего пространства вашего мода и проверить сразу всё рабочее пространство. Вы можете выбрать эту команду из контекстного меню или воспользоваться сочитанием клавиш Ctrl+E.

Если вы работаете в команде, то вам надо согласовывать кто над каким кодом работает или приготовиться к возможным последствиям работы над кодом без согласования...

Предупреждение:Не поддавайтесь искушению снять пометку "только для чтения" с файлов кода. Это рассинхронизирует Perforce и может привести к недоумению в будущем.

Использование контроля кода для интеграции обновлений SDK

We’ve now got source control up and running for your mod. It might have seemed complex, but this stuff will soon become grist for the mill. You can use source control as an ongoing backup, to compare code with what came before or after it, to revert changes, share code with others and contribute collaboratively, and, of course, to integrate trunk updates, which is what we'll be doing in this section.

Submit pending branch changes

This process only changes from our previous submits in that you will need to add any new files created since them to the depot. If you know precisely what's been created you can find each file manually and mark them for addition, but if you’ve got loads or aren’t sure (both will be the case if you’re importing the existing code you moved out earlier back into the workspace) it’s best to add the whole workspace.

You’ll need to do two extra things if you add the entire workspace:

1. Right-click on the new pending changelist and select the “Revert Unchanged Files” option, for obvious reasons.
2. Find and revert bin/, release_hl2/ and debug_hl2/ folders from game/server/ and game/client/, then do the same for any .ncb files (you can use Ctrl+F). These all contain very large amounts of auto-generated binary data that you don’t need or want version controlled. If you accidentally do submit any of these files, you can delete them from the database with a few console commands (these given without the confirming -y switch):
   • p4 obliterate //....ncb
   • p4 obliterate //depot/mymod/server/<folders>

Submit the changelist and we’ll move on.

Submit trunk update

The 'trunk' contains Valve’s unmodified SDK code, which now needs updating too. Before you open the SDK Launcher and install the new release however, remember that you need to check out the files to make them writeable. Just go to the workspace’s root and hit Ctrl+E.

Now you can install the new code(en); use the wizard's ‘Source code only’ option. After the installation mark all files in the valvesrc workspace for add to pick up anything new, then revert all unchanged files. Deleted files will have to be removed manually (if you think you’ve still got some lying around, search the valvesrc/ folder for files older than those from the SDK launcher install you just performed). Once that’s done submit, and we can move on to the fun part.

Integrate

We’ve now got fully updated code in both depots, so it’s time to integrate. You do this in the same manner as you populated the branch workspace: go to its root, then integrate with your valve_to_mymod branch.

The difference here is that you’ll need to resolve files that have changed between the versions. Since Perforce knows the point at which your mod code branched it can make a very good guess as to what version of a file should take precedence in most cases. You’ll usually only have to manually inspect the differences if you’ve made extensive changes to something, or if there’s a conflict that can’t be resolved automatically.

Otherwise you can accept the automatic result. Remember that you can always revert to the earlier, unmerged version of a file if the process later turns out to have gone wrong.

Совет:If Perforce queries a .lib file, always accept Valve's.

Manual merges

Нужно сделать: Link to documentation on P4's merge tool.

Test the new code

At this point, you should do a pass of the code to fix any compile errors that may have been introduced by the code merge. You could also do this pass before submitting the merged code changelist, but it tends to be easier to make changes starting with an empty changelist rather than one full of code merges.

And you're done!

Conclusion

Working with a source control introduces some concepts that take getting used to, but it pays dividends. It saves time, helps teams work together on the same product, and provides access to the whole history of a project.

Keep in mind that, while this document has a lot of steps, this stuff is all trivial once you're familiar with Perforce. Once you know how this all works, all these integrations and merges can be done in a matter of minutes. We recommend that you jump back to the "overview" section of this document to review the high-level process that is involved, and see how all the detailed steps fit into that simple high-level process.

Internally, Valve uses source control in a similar fashion to that described in this document. The main difference is that ALL files for Valve games go in Perforce, including content source .TGA artwork, .VMT files, executables, scripts, documents, etc. We recommend doing this while developing a mod as well, bandwidth limits and disc space allowing, because you can instantly restore any version of the mod that ever existed.

Valve also uses a multitude of codelines (whereas there are just two in this document). For example, we have a main codeline that about 20 programmers submit code into. Often programmers need to stay sheltered from other people's changes (which may happen as many as 19 times per day!), so each programmer has their own set of personal codelines that are branched off the main codeline. This way, they can choose when they want to integrate all the changes from other programmers into their personal codeline (just like you now have the choice about when you want to integrate Valve's source code into your mod's source code).

See also

• Official Perforce documentation
• Perforce Beginner's FAQ
• Integrating Perforce with Visual Studio