This is the toplevel directory for the cerea2 module. The first section describes the directory layout, and the second section describes quick usage instructions and the third section describes the the more advanced commands used to import and export data from the module to the CVS. ====== 1.0 Directory Layout ====== ===== 1.1 Module Contents ===== ^directory^ Contents^ |creatures|Text versions of the palette creature| |dialogs|Text versions of the palette dialogs| |encounters|Text versions of the palette encounters| |generic-scripts|Generic module scripts| |items|Text versions of the palette items| |other-scripts|Scripts which are not generic module scripts| |placeables|Text versions of the palette placeables| |sounds|Text versions of the palette sounds| |triggers|Text versions of the palette triggers| |visuals|XML files of the visuals| ===== 1.2 Other Files ===== |Makefile|Makefile to make it easier to import / export data| |bin|Perl programs used to import / export data| |perllib|Perl libraries used by the programs above| ====== 2.0 Importing and Exporting Data ====== ===== 2.1 Requirements ===== For windows you will need to install the two packages below: \\ http://tortoisecvs.sourceforge.net/download.shtml http://gnuwin32.sourceforge.net/downlinks/diffutils.php and if you have no perl installed: \\ http://downloads.activestate.com/ActivePerl/Windows/5.8/ActivePerl-5.8.8.819-MSWin32-x86-267479.msi Install them to the default directories with full settings. ===== 2.2 Setup ===== From start menu go to the 'Preferences' of tortoisecvs you and set in the tools tab: the "Diff Application:" to C:\Program Files\GnuWin32\bin\diff.exe In the start menu run command: cmd \\ In the opened command prompt run: "C:\Program Files\TortoiseCVS\cvs" -d :ssh:cerearo@www.cerea2.com:/home/cereacvs/cvsroot co cerea2 When promted for password, use the current ftp password for the main builders page. Create config file "config.pl" to this directory and put line module=c:/ ====== 3.0 Expanded usage ====== ===== 3.1 How to Start ===== First you need to checkout the files from the CVS. Normally this happens with the cvs -d www.cerea2.com:/home/cereacvs/cvsroot co cerea2 (you might need to set CVS_RSH environment variable to ssh or ssh2 depending on your environment). If you already have files checked out you can simply update them by saying cvs up Then you need to have the module where changes from the cvs are exported to. This module can either be directory having the module files, or the .mod file. The location of that can either be specified by the command line "--module " option to each script, or it can be written to the "config.pl" file in "module=" format. If command line option is given that overwrites the options specified in the "config.pl" file. The cvs does NOT contain all the data in the module, i.e some large data structures like area files are not there, so you need to have copy of some version of the module before you can start (either full version or stripped down partial version). Those files are distributed separately. ===== 3.2 Normal flow of work ===== Normally when you start working you first import your local changes from the module to the local cvs directory, then say cvs update to get updates from the remote cvs repository, and then if there was no conflicts you export changes from the cvs to your module. If there was conflicts during the cvs update you need to resolve those in the text format in the local cvs directory before continuing with the export. ===== 3.4 How to Export Data from CVS to Module ===== When you have the cvs repository checked out and you want to update changes from the CVS to the module, you can either simply say make cvstomodule or you can run the export command manually ./bin/cvstomodule.pl This will copy files from the CVS to the module. This WILL overwrite changes in the module. In normal case you first want to import changes from your module to CVS directory, then run cvs up and then export them back to module. This way you do not loose changes made to your module. ===== 3.5 How to Import Data Back from Module to CVS ===== After you have modified some files in the module and you finish your work (i.e. regardless whether you want to check modifications back to cvs or simply stop working for a while) it is good idea to import changes back from the module to the local CVS directory. This way if you later say CVS update and export files back you do not loose data. You can issue this command as often as you want (but you should not issue this after saying cvs update, as this will then copy old files from the module back) To import changes back from the module to local cvs directory say: make moduletocvs or you can run the import command manually ./bin/moduletocvs.pl This will check the module and copy modified files to the local CVS directory. After that you need to check them to cvs by saying cvs commit ===== 3.6 How to Copy New Files from Module to CVS ===== If you add new files to the module, and want to check them in to the CVS you need to specify those files. There is two ways to do that. If your files are following the default naming conventions, i.e. cxx__ then you can simply use -b (or --buildertag) option to specify the builder tag and all files matching your builder tag are copied to the cvs directory when you do import. I.e. ./bin/moduletocvs.pl -m ../module.mod -b tk will copy files from ../module.mod to CVS if they have builder tag tk. This does not yet add those files to cvs, you need to do that as a separate step by using cvs add for the given files. The script will put the files in the proper directories, but all scripts are put to the other-scripts directory, and if those scripts are supposed to be generic scripts, you should move them to generic-scripts directory before running cvs add. Another option to add files is to use -a (or --add) option. This can be used to add files which do not match your builder tag. The -a option is given a regexp that will match your files you want to copy from module to cvs. Example would be: ./bin/moduletocvs.pl -m ../moduledir -a ".*foo\.nss$" That command would copy files from the moduledir directory that are matching the given regexp (i.e. files which end with foo.nss) to the cvs directory. The scripts will be copied to the other-scripts as in previous case. ====== 4.0 Configuration file ====== All the options given to the commands can also be stored in the config file, so normally no options are needed if the module stays in the same location and buildertag etc do not change. The config file format is simple lines having "keyword = value". Supported keywords are: verbose \\ module \\ buildertag \\ The config file is simply created on the toplevel directory (i.e. in the same directory where this README is) with the name of "config.pl". Do not use backslashes in this file when specifying the module name, use forward '/' slashes instead.