SETUPPRJ.BAT

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

SETUPPRJ will create a BLD.BAT file in the GROUP directory and

read the LI.PRJ file in other second-level directories, creating

a BLD.BAT in each which will provide commands for building any

.BAT, .PL and .PM files to \epoc32\tools.

SETUPPRJ will also create \E32TOOLP\GROUP\E32TOOLP.REL

PERLPREP.BAT

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

PERLPREP strips "use strict;" debugging lines out

of .PL and .PM files and perl warning generation -w flag out of .BAT

files.  It is used for REL builds of E32TOOLP.

RELEASING E32TOOLP

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

make changes to source

change release.txt - update the date and "made by" details

add any new files which contain a version number to setver.bat

(remember perl files can use the service in E32TPVER.PM).

cd \e32toolp\group

run setver [version] to apply the latest version number.

cd \e32toolp

cvs commit to commit the version changes

cd \e32toolp\group

do setupprj to create the batch and .rel file

do bld clean

do bld rel

Prep the tree for release to PVCS:

cd \

perl \tools\pvcs-release.pl -f e32toolp

Tag the modules you're releasing:

cd \e32toolp

cvs tag E32TOOLPvNNN

Move the Latest-Release tag to the new files:

cvs rtag -d Latest-Release e32toolp

cvs rtag -r E32TOOLPvNNN Latest-Release e32toolp

cd \e32toolp\group

Create a vdiff.lis file with mnt difsrc <previous release>

do set vcsid=BASETEAM

do mnt lock  to make sure BASETEAM has the lock for all li.prj files

do mnt putsrc

do mnt versrc

do mnt putrel

do set vcsid=<your vcsid>

cd \e32toolp

Tag the release as complete (on the main branch)

	cvs tag Release-NNN-complete

go to the root of a clean drive

getrel e32toolp tools <version>

check it basically works - eg bldmake, makmake /mmp

rd /s /q epoc32

pgetbld e32toolp group

setupprj

bld rel

mnt valid

check \e32toolp\valid.lis

update Lotus Notes

update tlmakmak.rtf

OTHER INFO

==========

CASE SENSITIVITY

	Perl pattern-matching is twice as quick if it's done case-sensitive - keep

	all data uppercase except when it's actually being outputted - at that point

	it  can be formatted by doing something like ucfirst lc ...

	This is important so that pattern-matching done on data can assume

	uppercase.

CPP

	cpp assumes with -M and -MG that missing user headers live in the same directory as the

	source while missing system headers live in the first system include directory specified.

	This is not in fact true.  CPP always searches the directory containing the source file

	for headers if no user include path is specified explicitly.  Then, and only then, if the

	-MG option is specified to -M cpp will just bang out the missing files without a path,

	whether or not they exist in the current directory or not.  This means that if cpp is

	invoked in a makefile, (this probably applies to gcc too), cpp will fail unless these headers

	without a path exist in the working directory. 

	cpp doesn't replace lines of text within #defines within other #defines 

	with blank space if the lines aren't applicable for the current set of

	macros.  This can upset makmake's reporting of correct line numbers for errors.

	cpp documentation states that a space is put at the end of a macro expansion

	"most of the time".  We need to strip this back out after cpp has done its

	preprocessing in prepfile.pm.  By expanding macros to themselves with three

	leading underscores we can tell where a macro has been expanded and strip

	the space added.

MAKMAKE MODULE DESIGN

	the IDE/CL modules should provide

	a complete list of possible build variants and be designed in such a way that a particular

	implementation would not have to use all the builds if it didn't want to.  I think this

	will be the case already.  So, for example, if MISA could not do RELGDB the the CL_ARM code

	should never assume that all builds are required (except DEB or REL, which we must insist upon as a

	default in some cases).

QUOTES IN MAKEFILES

	Must be consistent with quotes round long filenames.  If remove quotes round .in

	file as a target to appease ar, the target will not be found and relgdb will not

	build.  It seems that without the quotes the filename is parsed so the leading .\

	on the front of the relgdb paths no longer makes a difference so rel and relgdb

	targets are considered the same.  This means that rules for the rel and relgdb .in

	file, if it is around this target that the quotes are removed, and all subsequent

	dependencies and rules, will be done for each source file - eg gcc looks like it

	will be called twice with different flags.  For the relgdb build nmake will complain

	that it doesn't know how to build the .in file because it sees it as a dependency of

	the main target with quotes and doesn't recognise it as the same thing appearing later

	as a target without quotes because the .\ is parsed out.  The rel build doesn't complain

	because it has no preceding .\ to parse out.  In short, filenames without quotes are parsed and

	amount to the same thing as filenames with quotes if the only difference between the two is the

	quotes and not the path itself.

COMPILER FLAGS

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

ALL BUILDS

/nologo    - dont display the banner

/Zp4       - Zp[n] - pack structs on n-byte boundary (whatever that means) /W4        - top level warnings

/Fo<file>  - specifies object file (left blank so base name taken from .cpp     

file)

/c         - compile only, don't link because we'll be linking later

SPECIAL CASES

/ML     - Use run-time library -> Single-threaded       (WINS exe release) /MD     - Use run-time library -> Multi-threaded DLL    (WINS dll release)

these two flags have "d" appended for debug builds so that the respective debug run-time library is used instead.  These flags are probably unnecessary for all projects not using Win32 libraries but MSVC puts them in by default, and it doesn't do any harm to have them I don't think

/O1     - minimum size optimisation (WINS release)

/Ob1    - disable inline function expansion (WINS release)  (reason uncertain!)

/Od     - disable optimisations (WINS debug)

/Zi     - generate debugging info into program database (WINS debug)

/FR     - generate browse info (WINS debug)

/Fd<file>     - name program database (WINS debug)

/X      - suppresses searching of include directories specified by environmental

include variable (so used for all projects not using Win32 services)

LINKER FLAGS

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

ALL BUILDS

/nologo                 - suppress startup banner /subsystem:windows      - MSVC always puts this in anyway /machine:IX86           - ditto

/out:<file>             - specifies filename for target /WARN:3                 - top-level warnings

/nodefaultlib           - don't use Win32 libraries (if any are being used then 

they are listed before this flag and so are not        

affected by it)

SPECIAL CASES

/baseaddress:<hex num>  - base address for DLLs, specified by user /entry:"_E32Startup"    - EPOC32 entry point for EXEs /entry:"_E32Dll"        - EPOC32 entry point for DLLs

/incremental:no         - (WINS release) - presumably so a full-link is always  

performed

/incremental:yes        - (WINS debug)  - presumably to save time linking-fully 

when working on a project

/dll                    - (WINS dll targets)

/pdb<file>              - (WINS debug) <file> names program database

/deffile:<file>         - (WINS dll targets) <file> specifies a def file to     

refer to if one is specified by the user

/implib:<file>          - specifies name of import library to be created for dll

targets if one is to be created

/debug                  - (WINS debug)  generates debugging information

SOURCES OF INFORMATION FOR MAKMAKE ETC

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

NMAKE Reference in MSVC help

Cygnus help files in R:\gcc\help - eg cpp.hlp

Lotus notes - Epoc Software Design - Development Environment - suggestions

for better build procedures

Perl newsgroups