cm3Proj.CMD Documentation

(last updated 08/29/2003 by RCC)

Purpose:

This Windows batch/command file aids users is building, shipping, cleaning, and archiving sources for a set of Modula-3 packages rooted at a common folder (i.e., path).

Author / Distribution Rights:

Randy Coleburn, Senior Systems Engineer, Scientific Research Corporation
2300 Windy Ridge Parkway, Suite 400 South, Atlanta, GA 30339

Author grants free use/modification/distribution of this batch/command file to anyone.
Author does not warrant this batch/command file. Use at your own risk.

I can't promise to maintain this software, but if you have a problem or suggestion, you are welcome to send me an email at rcoleburn@mindspring.com
I will try to respond in a timely manner.

Caveats:

You must be running WindowsNT4SP6, Windows2000, or Windows XP with command extensions enabled; otherwise, this command file will fail.

Installation / Setup:

Store this file in the bin directory of your cm3 installation.

Dependencies:

The CM3SetupCmdEnv.CMD file, cm3.exe, TAR.exe, and GZip.exe must be in the bin directory of your cm3 installation. They are used by this command file.

Environment Variable Usage:

This command file makes use of the CM3SetupCmdEnv.CMD file, which sets up the following five environment variables automatically:

CM3_ROOT is the root of the CM3 installation, typically "C:\cm3"
CM3_BIN is where the CM3 binaries are kept, typically "C:\cm3\bin"
CM3_PKG is the location of the public package repository, typically "C:\cm3\pkg"
CM3_DoneSetup indicates if this command file completed successfully.
REACTOR_HOME is where Reactor looks for the user's home folder.

The following environment variables are used internally and are considered temporary:

CM3P_Answer, CM3P_Archive, CM3P_cm3Opts, CM3P_DefaultInstallRoot, CM3P_Fatal, CM3P_File, CM3P_List, CM3P_Make, CM3P_Nest, CM3P_Pause, CM3P_PriorFolder, CM3P_ProjName, CM3P_ProjRoot, and CM3P_SavePrompt.

File Usage:

This batch/command file uses text files named "name.CM3P" where "name" is the name of the project. These files are stored in the root project folder (i.e., the folder containing the various package folders comprising the project). These files specify the contents and build order for the packages in the project. See Help text (below) for details.

User Help:

Basic Usage:
Usage:  cm3Proj Project Command Option cm3Options
        cm3Proj Help
        cm3Proj Remarks
where,

Project is the pathname (absolute or relative to current folder) of the .CM3P project file, without the .CM3P extension, e.g. myPath\myProject

Command is one of: Make, Build, Clean, Ship, Find, Spotless, ArcSrc, ZapBak, DelNT386, List, Local, Depend, Help, or Remarks

Option is either omitted, or one of: NoPause
Unless "NoPause" is specified, whenever cm3.exe returns an error, the user is prompted to "Press any key to continue..." Omitting the "NoPause" option is useful to highlight problems with individual packages when building large numbers of packages.
When used with the "List" command, "NoPause" prevents the user from being prompted to "Press any key to continue..." after each package listing.

cm3Options are any valid command line options to cm3.exe. These will be passed to cm3.exe without verification.

For each package/project (yes you can nest projects) specified in the "Project.CM3P" file, "Command" is carried out.

Case of commands and options is not significant. Use "cm3Proj Help" or "cm3Proj Remarks" for more helpful information.

Detailed Command Descriptions:

The meaning of each command is as follows:

ArcSrc Using TAR and GZIP, create the source archive [Project]_Sources.tgz This compressed tar file contains all of the project's source files, i.e., those in the package src folders. Note that the tree structure of the packages is preserved.

Build Build and ship, i.e. cm3 -build followed by cm3 -ship (note: the ship step is skipped if the build is unsuccessful)

Clean cm3 -clean

DelNT386 Delete derived NT386 folders within the project's packages.

Depend Display package dependencies, i.e., cm3 -depend

Find Locate source files, i.e., cm3 -find

Help Display this summary of helpful information.

List List files comprising each package's folder tree.

Local Build locally; do not ship to the public repository, i.e. cm3 -build

Make Assume the current folder is the project root. Scan this folder for packages. Packages are detected by the presence of the file "pkg\src\m3makefile", where pkg is any subfolder within the file system tree rooted at the current folder. Create a new project file named ".\Project.CM3P" containing all of the packages found. You should probably edit this file to reorder the packages in the correct compilation/build order wrt package dependencies.

Ship Install private packages in the public repository, i.e., cm3 -ship

Remarks Display helpful remarks embedded at the beginning of this command file.

Spotless Delete derived NT386 folders within the local (private) packages and also delete the corresponding package folders from the public repository (typically rooted at C:\cm3\pkg). Note that for the public package folders, the entire folder, including "src", "NT386", and other platform subfolders are deleted.

ZapBak Delete all backup files within the package folders. A file is considered to be a backup file if its last extension is ".bak".

.CM3P File Format:

The file contains one or more text lines. Each line can be one of the following four types, subject to the constraints and interpretation given:

;comment
NAME ThisProject
PKG PathToPackageRoot
PROJ PathToProjectRoot NestedProject

Spaces and tabs are considered delimiters, thus "ThisProject", "NestedProject", "PathToPackageRoot", and "PathToProjectRoot" cannot contain embedded spaces/tabs. "ThisProject.CM3P" must be the actual filename (no path) of the file.
The semicolon (;) is treated as an end-of-line comment character. That is, any characters following a semicolon are ignored.
"NAME", "PKG", and "PROJ" are case-sensitive keywords.
Only one NAME, PKG, or PROJ specification is permitted per line.
The "NAME" keyword defines "ThisProject" as the name of this project. The NAME directive must be the first non-comment line in the file. Only one NAME directive is permitted per file.
The "PKG" keyword defines "PathToPackageRoot" as a package. "PathToPackageRoot" is the absolute or relative path to the folder containing the package's "src" subfolder.
The "PROJ" keyword defines "NestedProject" as a project containing a "PathToProjectRoot\NestedProject.CM3P" file. Nesting of projects is permitted up to whatever limit is imposed by the Windows command processor.
Multiple PKG and PROJ specification lines can occur in the file.
The order of the PKG and PROJ specification lines is the order that the packages and projects will be considered by cm3Proj for each "Command" action. A nested project is processed and completed before continuing further in the parent project file.
WARNING: A nested PROJ specification that specifies a project that is already part of the "tree of projects" will cause infinite recursion!

Example .CM3P File:

The following example illustrates how the entire v526 source distribution can be built and shipped using cm3Proj. Assume that the source tree is located at C:\cm3\Sources and that the file C:\cm3\Sources\v526_allSources.CM3P exists and contains the lines shown below. The command "cm3Proj C:\cm3\Sources\v526_allSources build" could be used to build and ship the entire distribution. Alternately, if the current directory is already C:\cm3\Sources, the command could be given as: cm3Proj v526_allSources build

v526_allSources.CM3P

NAME v526_allSources
PKG m3-libs\m3core
;**TEST** PKG m3-libs\m3core\tests\float
;**TEST** PKG m3-libs\m3core\tests\text
PKG m3-libs\libm3
;**TEST** PKG m3-libs\libm3\tests\fmtlex\fmt
;**TEST** PKG m3-libs\libm3\tests\fmtlex\lex
;**TEST** PKG m3-libs\libm3\tests\fmtlex\scan
;**TEST** PKG m3-libs\libm3\tests\os
;**TEST** PKG m3-libs\libm3\tests\pqueue\fromtty
;**TEST** PKG m3-libs\libm3\tests\pqueue\heapsort1
;**TEST** PKG m3-libs\libm3\tests\pqueue\heapsort2
;**TEST** PKG m3-libs\libm3\tests\random
;**TEST** PKG m3-libs\libm3\tests\rw\autotest
;**TEST** PKG m3-libs\libm3\tests\rw\copy
;**TEST** PKG m3-libs\libm3\tests\rw\pump
;**TEST** PKG m3-libs\libm3\tests\rw\pumprd
;**TEST** PKG m3-libs\libm3\tests\sequence
;**TEST** PKG m3-libs\libm3\tests\sortedtable
;**TEST** PKG m3-libs\libm3\tests\sqrt
PKG m3-sys\m3middle
PKG m3-sys\m3quake
PKG m3-sys\m3scanner
PKG m3-sys\m3tools
PKG m3-sys\m3cgcat
PKG m3-sys\m3cggen
PKG m3-tools\m3bundle
PKG m3-sys\mklib
PKG m3-sys\dll2lib
PKG m3-sys\fix_nl
PKG m3-sys\libdump
PKG m3-libs\bitvector
;**TEST** PKG m3-libs\bitvector\test
PKG m3-libs\digraph
PKG m3-libs\parseparams
PKG m3-libs\realgeometry
PKG m3-libs\set
PKG m3-libs\slisp
;**TEST** PKG m3-libs\slisp\tests
PKG m3-libs\sortedtableextras
;**TEST** PKG m3-libs\sortedtableextras\tests\intperf
;**TEST** PKG m3-libs\sortedtableextras\tests\leveltest
;**TEST** PKG m3-libs\sortedtableextras\tests\randtest
;**TEST** PKG m3-libs\sortedtableextras\tests\rbtest
;**TEST** PKG m3-libs\sortedtableextras\tests\sltest
PKG m3-libs\table-list
PKG m3-libs\tempfiles
PKG m3-comm\tcp
PKG m3-libs\libsio
PKG m3-libs\libbuf
PKG m3-libs\debug
PKG m3-libs\listfuncs
PKG m3-libs\patternmatching
;**TEST** PKG m3-libs\patternmatching\tests
PKG m3-libs\embutils
PKG m3-libs\m3tk-misc
PKG m3-www\http
PKG m3-libs\binIO
;**TEST** PKG m3-libs\binIO\test
PKG m3-comm\tapi
PKG m3-comm\serial
;**TEST** PKG m3-comm\serial\test
PKG m3-tools\m3tk
PKG m3-tools\mtex
PKG m3-tools\m3totex
PKG m3-tools\m3tohtml
PKG m3-tools\m3scan
PKG m3-tools\m3markup
PKG m3-tools\m3browser
PKG m3-tools\cmpdir
PKG m3-tools\cmpfp
PKG m3-tools\dirfp
PKG m3-tools\uniq
PKG m3-comm\netobj
;**TEST** PKG m3-comm\netobj\tests\echorw
;**TEST** PKG m3-comm\netobj\tests\fd
;**TEST** PKG m3-comm\netobj\tests\fd1
;**TEST** PKG m3-comm\netobj\tests\longcall
;**TEST** PKG m3-comm\netobj\tests\luca
;**TEST** PKG m3-comm\netobj\tests\perf
;**TEST** PKG m3-comm\netobj\tests\pkl
PKG m3-comm\netobjd
PKG m3-comm\stubgen
PKG m3-comm\events
;**TEST** PKG m3-comm\events\tests\msg
;**TEST** PKG m3-comm\events\tests\test
;**TEST** PKG m3-comm\events\tests\work
PKG m3-comm\rdwr
;**TEST** PKG m3-comm\rdwr\test\echo
;**TEST** PKG m3-comm\rdwr\test\john
PKG m3-comm\sharedobj
;**TEST** PKG m3-comm\sharedobj\tests\netobjtest
;**TEST** PKG m3-comm\sharedobj\tests\obsequence
;**TEST** PKG m3-comm\sharedobj\tests\tracker
PKG m3-comm\sharedobjgen
;**TEST** PKG m3-comm\sharedobjgen\test\trackerpos
PKG m3-db\odbc
;**TEST** PKG m3-db\odbc\test
PKG m3-db\postgres95
;**TEST** PKG m3-db\postgres95\test
PKG m3-db\db
;**TEST** PKG m3-db\db\test
PKG m3-db\smalldb
PKG m3-db\stable
;**TEST** PKG m3-db\stable\example
;**TEST** PKG m3-db\stable\test
PKG m3-db\stablegen
PKG m3-ui\ui
;**TEST** PKG m3-ui\ui\test\Argus
;**TEST** PKG m3-ui\ui\test\BadBricks
;**TEST** PKG m3-ui\ui\test\ButtonTest
;**TEST** PKG m3-ui\ui\test\Cards
;**TEST** PKG m3-ui\ui\test\ColorMonster
;**TEST** PKG m3-ui\ui\test\Draw
;**TEST** PKG m3-ui\ui\test\EyesVBT
;**TEST** PKG m3-ui\ui\test\Hello
;**TEST** PKG m3-ui\ui\test\Monster
;**TEST** PKG m3-ui\ui\test\Sketch2
;**TEST** PKG m3-ui\ui\test\StarAnim
;**TEST** PKG m3-ui\ui\test\Track
;**TEST** PKG m3-ui\ui\test\TypeInTest
;**TEST** PKG m3-ui\ui-tests\pixmapcomtest
;**TEST** PKG m3-ui\ui-tests\pixtest
;**TEST** PKG m3-ui\ui-tests\test18
;**TEST** PKG m3-ui\ui-tests\test19
;**TEST** PKG m3-ui\ui-tests\test25
;**TEST** PKG m3-ui\ui-tests\test26
;**TEST** PKG m3-ui\ui-tests\test27
;**TEST** PKG m3-ui\ui-tests\test28
;**TEST** PKG m3-ui\ui-tests\test29
;**TEST** PKG m3-ui\ui-tests\test30
;**TEST** PKG m3-ui\ui-tests\test31
;**TEST** PKG m3-ui\ui-tests\test32
;**TEST** PKG m3-ui\ui-tests\test33
;**TEST** PKG m3-ui\ui-tests\test35
;**TEST** PKG m3-ui\ui-tests\texturecomtest
;**TEST** PKG m3-ui\ui-tests\tiles
;**TEST** PKG m3-ui\ui-tests\track
PKG m3-ui\PEX
PKG m3-ui\vbtkit
PKG m3-ui\cmvbt
PKG m3-ui\jvideo
PKG m3-ui\videovbt
PKG m3-www\web
PKG m3-ui\formsvbtpixmaps
PKG m3-ui\formsvbt
PKG m3-ui\formsview
PKG m3-ui\formsedit
PKG m3-ui\codeview
PKG m3-ui\mg
PKG m3-ui\mgkit
PKG m3-ui\opengl
PKG m3-ui\anim3D
PKG m3-ui\zeus
PKG m3-ui\m3zume
PKG m3-obliq\synloc
PKG m3-obliq\synex
PKG m3-obliq\metasyn
PKG m3-obliq\obliqrt
PKG m3-obliq\obliqparse
PKG m3-obliq\obliqprint
PKG m3-obliq\obliq
PKG m3-obliq\obliqlibemb
PKG m3-obliq\obliqlibm3
PKG m3-obliq\obliqlibui
PKG m3-obliq\obliqlibanim
PKG m3-obliq\obliqsrvstd
PKG m3-obliq\obliqsrvui
PKG m3-obliq\obliqbinmin
PKG m3-obliq\obliqbinstd
PKG m3-obliq\obliqbinui
PKG m3-obliq\obliqbinanim
PKG m3-obliq\visualobliq
PKG m3-obliq\vocgi
PKG m3-obliq\voquery
;**FAILS ON NT386** PKG m3-obliq\vorun
PKG m3-ui\webvbt
PKG m3-tools\recordheap
PKG m3-tools\rehearsecode
PKG m3-tools\replayheap
PKG m3-tools\showheap
PKG m3-tools\shownew
PKG m3-demo\cube
PKG m3-demo\calculator
PKG m3-demo\fisheye
;
;PKG m3-sys\cm3
;PKG m3-sys\cminstall
;PKG m3-sys\m3back
;PKG m3-sys\m3cc
;PKG m3-sys\m3front
;PKG m3-sys\m3gdb
;PKG m3-sys\m3linker
;PKG m3-sys\m3loader
;PKG m3-sys\m3objfile
;PKG m3-sys\m3staloneback
;**TEST** PKG m3-sys\m3tests
;
PKG m3-sys\windowsResources
PKG m3-sys\reactor
;
;**FAILS ON NT386** PKG m3-libs\dps
;**FAILS ON NT386** PKG m3-libs\m3gc-enhanced
;**FAILS ON NT386** PKG m3-libs\m3gc-simple
PKG m3-libs\tcl
;**TEST** PKG m3-libs\tcl\test
;
;**FAILS ON NT386** PKG m3-tools\coverage
;**NEEDS LEX/YACC/FLEX/BISON** PKG m3-tools\gnuemacs
PKG m3-tools\hexdump
;**NOT FOR NT386** PKG m3-tools\macapi
;**NEEDS LEX/YACC/FLEX/BISON** PKG m3-tools\pp
;**NOT FOR NT386** PKG m3-tools\showthread
;
;**FAILS ON NT386** PKG m3-pkgtools\pkgobj
;**FAILS ON NT386** PKG m3-pkgtools\pkgfprint
;**FAILS ON NT386** PKG m3-pkgtools\pkgq
;**FAILS ON NT386** PKG m3-pkgtools\pkgsrv
;**FAILS ON NT386** PKG m3-pkgtools\pkgtool
;
PKG m3-db\pgodbc
;
PKG m3-comm\udp
;**TEST** PKG m3-comm\udp\test
;
PKG m3-ui\bicycle
PKG m3-ui\images
PKG m3-ui\juno-2\juno-machine
;**TEST** PKG m3-ui\juno-2\juno-machine\linear
;**TEST** PKG m3-ui\juno-2\juno-machine\nonlinear
;**TEST** PKG m3-ui\juno-2\juno-machine\runtime
;**TEST** PKG m3-ui\juno-2\juno-machine\solve
PKG m3-ui\juno-2\juno-compiler
;**TEST** PKG m3-ui\juno-2\juno-compiler\tests\compiler
;**TEST** PKG m3-ui\juno-2\juno-compiler\tests\lexer
;**TEST** PKG m3-ui\juno-2\juno-compiler\tests\parser
;**TEST** PKG m3-ui\juno-2\juno-compiler\tests\scope
PKG m3-ui\juno-2\juno-app\pkl-fonts
PKG m3-ui\juno-2\juno-app
PKG m3-ui\motif
;**TEST** PKG m3-ui\motif\tests
;**FAILS ON NT386** PKG m3-ui\webvbt\src\hyperpage
PKG m3-ui\X11R4
;
;**FAILS ON NT386** PKG m3-mail\llscan
;**FAILS ON NT386** PKG m3-mail\postcard
;**FAILS ON NT386** PKG m3-mail\webcard
;
PKG m3-www\deckscape
PKG m3-www\proxy
PKG m3-www\webcat
PKG m3-www\webscape
;
PKG m3-lectern\ocr
;**FAILS ON NT386** PKG m3-lectern\lecterndoc
;**FAILS ON NT386** PKG m3-lectern\buildlectern
;**FAILS ON NT386** PKG m3-lectern\lecternclient
;**FAILS ON NT386** PKG m3-lectern\editlectern
;**FAILS ON NT386** PKG m3-lectern\lectern
;**FAILS ON NT386** PKG m3-lectern\lecterntohtml
;
;**FAILS ON NT386** PKG m3-obliq\obliqlib3D
;**FAILS ON NT386** PKG m3-obliq\obliqbin3D
;
;**FAILS ON NT386** PKG m3-demo\dpsslides
PKG m3-demo\mentor
PKG m3-demo\sharedboard\board
;**FAILS ON NT386** PKG m3-demo\sharedboard\boardclient
;**FAILS ON NT386** PKG m3-demo\sharedboard\boardserver
PKG m3-demo\sharedboard\calendar
;**FAILS ON NT386** PKG m3-demo\sil
;
PKG m3-games\badbricks
PKG m3-games\columns
PKG m3-games\fours
PKG m3-games\maze
PKG m3-games\solitaire
PKG m3-games\tetris

Project	is the pathname (absolute or relative to current folder) of the .CM3P project file, without the .CM3P extension, e.g. myPath\myProject
Command	is one of: Make, Build, Clean, Ship, Find, Spotless, ArcSrc, ZapBak, DelNT386, List, Local, Depend, Help, or Remarks
Option	is either omitted, or one of: NoPause Unless "NoPause" is specified, whenever cm3.exe returns an error, the user is prompted to "Press any key to continue..." Omitting the "NoPause" option is useful to highlight problems with individual packages when building large numbers of packages. When used with the "List" command, "NoPause" prevents the user from being prompted to "Press any key to continue..." after each package listing.
cm3Options	are any valid command line options to cm3.exe. These will be passed to cm3.exe without verification.

ArcSrc	Using TAR and GZIP, create the source archive [Project]_Sources.tgz This compressed tar file contains all of the project's source files, i.e., those in the package src folders. Note that the tree structure of the packages is preserved.
Build	Build and ship, i.e. cm3 -build followed by cm3 -ship (note: the ship step is skipped if the build is unsuccessful)
Clean	cm3 -clean
DelNT386	Delete derived NT386 folders within the project's packages.
Depend	Display package dependencies, i.e., cm3 -depend
Find	Locate source files, i.e., cm3 -find
Help	Display this summary of helpful information.
List	List files comprising each package's folder tree.
Local	Build locally; do not ship to the public repository, i.e. cm3 -build
Make	Assume the current folder is the project root. Scan this folder for packages. Packages are detected by the presence of the file "pkg\src\m3makefile", where pkg is any subfolder within the file system tree rooted at the current folder. Create a new project file named ".\Project.CM3P" containing all of the packages found. You should probably edit this file to reorder the packages in the correct compilation/build order wrt package dependencies.
Ship	Install private packages in the public repository, i.e., cm3 -ship
Remarks	Display helpful remarks embedded at the beginning of this command file.
Spotless	Delete derived NT386 folders within the local (private) packages and also delete the corresponding package folders from the public repository (typically rooted at C:\cm3\pkg). Note that for the public package folders, the entire folder, including "src", "NT386", and other platform subfolders are deleted.
ZapBak	Delete all backup files within the package folders. A file is considered to be a backup file if its last extension is ".bak".