home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Monster Media 1994 #1
/
monster.zip
/
monster
/
PROG_GEN
/
PJ110.ZIP
/
CBACK.EXE
/
PJ.MAN
< prev
next >
Wrap
Text File
|
1994-02-24
|
21KB
|
438 lines
PJ User's Manual
Revision A
February 23, 1994
Copyright (C) 1994 MICROTOOLSIntroduction
PJ is a simple source file manager for use on moderate size software
projects (20 - 5,000 source files) utilizing a shared project library with 1-
20 programmers.
PJ is intended to solve the following problems:
Avoid costly collisions between programmers modifying the same
file.
Eliminate programmer maintenance when extracting and adding files
from and to a library.
Prevent loss of work by maintaining multiple versions of the same
file in a library. Older versions of the same file can be retrieved.
What PJ provides:
■ Library check out control - only one programmer can have a
source file out for modification at a time.
■ Automatic updating of Make and Library command files -
when the programmer puts a new module into the library, the
Make and Library command files can be automatically updated
■ Automatic insertion/removal with the programmers Make
file(s) - when the programmer removes a source file from a
library, the programmers local Make file is updated to allow
the programmer to modify the file and reference it in their
local directory. When the file is put back in the library, the
local Make file is updated to remove the file. Additional files
can be deleted from the local directory.
■ Automatic "BAK" versions of up to 1000 files per library - PJ
allows you to keep up to 1000 "bak" versions of library files per
library.
Description of the Development Environment
PJ was developed for a medium scale two programmer software project
developing four similar embedded systems (approximately 40,000 lines
of code in 1000 modules). Borland C++ was used for the development
cycle. A Novell network server was used as the source library.
However PJ is flexible enough to allow utilization in many other
environments (Including MicroSoft C/C++). Each programmer had
their own working directory with a baseline Make file. Within the
programmer's working directory, one of the four systems could be built
at a time. Additional working directories could be used if simultaneous
development of the four systems was required.
Several different directories housed the source library files. The
programmer did not need to know which library he was removing the
file from (this assumes that no two files are named the same for a given
system).
Associated with each library directory, is a Make file and a Library
command file (You can configure these differently). When a new file is
added by a programmer to the library, the Make file and library
command file is updated.
This manual is written assuming you understand the concepts of source
file librarians and make utilities. The examples given utilize Borland
C++ 3.1 MAKE and TLIB formats.
Registration Benefits
If you register PJ for $25, in addition to a "no nag" version, a printed
manual, unlimited technical support, and free upgrade policy, we will
also provide the source code (in Borland C++ version 3.1 format) for
the source file manager (source code for the automatic backup will not
be provided). This will allow you to modify PJ to meet any unforseen
requirements.
Using PJ
Removing Files from the library
From the programmer's working directory, a file can be removed from
the library with the following command:
pj - FILENAME
where FILENAME specifies the name of the file(s) to remove
from the program library. This specification may include
wildcards and need not specify the extension. PJ will search
all of the library directories specified in PJ.CFG for a match
of the filename (with the configured extension). The file will
be marked read only in the library.
If the file has already been extracted, the following message will be
displayed:
Unable to extract FILENAME.EXT - File already extracted
If the file cannot be found in the library, the following message will be
displayed:
Unable to find file FILENAME
To remove a file without modifying the files specified in the PJ.CFG
(for example to remove an .H file), the user should specify the file
extension (and that file extension should not be in the PJ.CFG). PJ will
search all of the libraries specified in PJ.DIR and attempt to find the file
specified. When this file is returned to the library, the corresponding
files (for example the Make file) will not be modified.
Inserting Files into the library
From the programmer's working directory, a file can be added to the
library with the following command:
pj + FILENAME
where FILENAME specifies the name of the file(s) to add to the
program library. This specification may include wildcards and
need not specify the extension. PJ will search all of the
library directories for a match of the filename and add it to
one or more of the defined libraries. If FILENAME is not
specified, all files extracted by the programmer will be
returned to their respective libraries.
If the file has not been extracted, the following message will be
displayed:
Unable to add FILENAME - File not in EXT_LIST.DIR; Use full
path for new files
If a new file is being added to the library, the user should specify the
full filename (including path and extension). This will place the new file
in the library specified by the path and modify the files specified in
PJ.CFG.
Restarting a file in your Local Directory
Sometimes (although we hope, not very often), you remove a file from a
library, make a fix, test the fix and find that you don't want to put the
modified file back in the library. The * command, allows you to take
the file specified in the library and overwrite your changes in your local
directory. This can be a dangerous operator if not used properly.
Library BAK files
PJ provides a powerful tool for maintaining up to 1000 old versions of
files in a given library through inclusion of MICROTOOLS ComeBack
program (See the ComeBack user manual in the Appendix of this
document - COMEBACK.MAN). ComeBack can be configured to
maintain the last 1000 files that were deleted and overwritten for a given
Drive. If you configure your source library as a drive (using the
network mapping function or DOS SUBST), each library can be
configured to protect your source files. Using ComeBack's configuration
program, (CBCONFIG), you can specify what drives you desire to
include and what files you desire to have protected (For example,
ComeBack can be configured to only protect .CPP, .H, .MAK and .BLD
files).
An older version of a file can easily be retrieved using the COMEBACK
program.
Configuring PJ
Configuring PJ requires the programmer to set up the following files:
(NOTE: All configuration file lines are limited to 200 characters each)
PJ.DIR This file defines the library files and the associated
extensions used in the project. For example, let's
assume that you have four libraries on your H:
drive entitled: COMMON, ENGINE, MAIN and
RATES. In the first three libraries, .CPP files are
kept. In the RATES directory, .RAT, .RT1, .RT2,
.RM1 and .RM2 files are kept. The PJ.DIR file
would look like:
h:\common\*.cpp
h:\engine\*.cpp
h:\MAIN\*.cpp
h:\rates\*.rat
h:\rates\*.rt1
h:\rates\*.rt2
h:\rates\*.rm1
h:\rates\*.rm2
This file is limited to 200 entries
PJ.CFG This file tells PJ what to do with a file when it is
extracted from and returned to the library.
Multiple lines can be used to define each operation.
For example, one file may need to be modified in
several places in different ways during an extract.
Thus two entries would be required. For example,
in our configuration, when a file is extracted from
a library, we want it to be inserted in the local
directory's make file. We need to tell PJ what file
to modify (in our case, the make file), and where
in the make file to insert the file. We need to tell
PJ how to insert the file into the make file (a Prefix
and a Suffix to the line). Each item is delimited by
a comma. If a comma is desired on the command
line, it should be prefaced with a double quote (").
When a file is extracted or returned by PJ, the
following line is added to specified file:
PREFIXFileExtractedSUFFIX
Thus the PJ.CFG file consists of a definition of the
extract (-) or replace (+) operator:
OPERATOR,FILENAME,PREFIX,SUFFIX,AFTER HERE
STRING,.EXT,.EXT,...etc
where:
OPERATOR is the definition operator
(either a + or a -)
- operators are used to extract files
from a library and specify how to
modify files in your local directory
for both - and + operators.
+ operators are used to put files back
into the library and to specify how
to modify files in the library's
directory when the + operator is
used to add a new file.
FILENAME is the name of the file to
modify (in our case - the make file).
For the + operator, if only an
extension is used (.MAK for
example), the filename of the library
directory will be used for the
filename. For example, if the
programmer is inserting a new file
into the COMMON directory, the
COMMON.MAK file will be updated.
PREFIX is the comma delimited string to go
on the line being added to
FILENAME before the file being
extracted is added to the line
SUFFIX is the comma delimited string to go
on the line being added to
FILENAME after the file being
extracted is added to the line
AFTER HERE STRING is the comma
delimited string to tell PJ where to
insert the line being added to
FILENAME. PJ searches
FILENAME for the AFTER HERE
STRING, and inserts the line after this
line. If not specified, PJ inserts the
file at the beginning of FILENAME.
EXT is the extension of the files that can be
automatically extracted/returned
without specifying the extension as
well as the files that will be inserted
into the FILENAME. Files with
extensions not part of this list will
result in the file being
extracted/returned but FILENAME
will not be updated. For example, .C
and .CPP files will be included in this
list, because these are source files to
be included in the local make.
However, .H files will not be included
as these files can be removed from the
library but the make file need not be
modified. Up to twenty extensions
can be configured on each line.
For example, with our Borland C++ compiler, our
first extract line in PJ.CFG looks as follows:
-,makefile,,.OBJ \,$(MARK_1)
If multiple entries are required, a second extract
definition line can be defined. Our second line
looks as follows:
-,makefile,, +,$(MARK_2)
The $ character is used in the Borland make file to
indicate a macro (which in our case is not defined).
Those lines are inserted in the makefile. The
following represents a sample makefile:
####################### BORLAND C++ MAKEFILE
#######################
lsw = /v /c /m /s
csw =
cppmodel = -ml
DRIVE = H
.cpp.obj:
bcc $(csw) -zEtest_seg $(cppmodel) {$< }
.rm2.obj:
bcc $(csw) $(cppmodel) -zEmenu_seg {$< }
.rm1.obj:
bcc $(csw) $(cppmodel) -zEmenu_seg {$< }
.rat.obj:
bcc $(csw) $(cppmodel) -zErat_seg {$< }
.rt1.obj:
bcc $(csw) $(cppmodel) -zErat_seg {$< }
.rt2.obj:
bcc $(csw) $(cppmodel) -zErat_seg {$< }
.precious: MAIN.exe
MAIN.exe: makefile \
$(DRIVE):\MAIN\MAIN.lib \
$(MARK_1) \
TASKINIT.obj
tlink $(lsw) @&&!
c0l +
$(MARK_2) +
TASKINIT +
, MAIN, MAIN, $(DRIVE):\MAIN\MAIN + $(DRIVE):\MAIN\COMMON
$(DRIVE):\MAIN\rates +
$(DRIVE):\MAIN\engine
!
#End##################### BORLAND C++ MAKEFILE
#######################
The return operator works in a similar fashion.
Files can be modified in the directory from which
the module came using the same syntax. This
operation only occurs when a new file is being
inserted into the library (i.e. when the programmer
specifies the path). In our environment, the return
operator specification in PJ.CFG modifies a make
file used to compile the library modules as well as
a library command file to insert the files into the
library. Files that are listed for modification that
do not exist in the directory will not be created nor
will an error be generated. This allows the
programmer to have multiple make files for a given
library.
In our environment, each library has a .MAK
associated with it and a .BLD associated with it.
The .MAK is used to compile the modules. The
.BLD is used to insert the .OBJs into the library.
The PJ.CFG definition in this case would appear as
follows:
+,.MAK,,.OBJ \,$(MARK_1),.CPP,.C,.ASM
+,.BLD,+ ,.OBJ &,,.CPP,.C,.ASM
The following defines a simple TLIB .BLD file:
+ACCESS &
+DO_EVENT &
+DSP_OBJ &
+DSPERROR &
+DSPFUNCS &
+PASSWORD &
+Q_EVENT &
+SOFT_KEY &
+STATE_EN &
+
In addition to the extract (-) and return (+)
operators, there is one additional operator (*). The
* operator in the PJ.CFG file defines what file
extensions should be deleted when a file is removed
from the local library (with the + operator). For
example, when a .CPP file is returned to the
library, .OBJ, .BAK, and .ERR files should be
deleted. Up to twenty extensions can be defined
with the * operator. This would be specified in
PJ.CFG as follows:
*,.OBJ
*,.BAK
*,.ERR
In summary, for a Borland C++ development
environment, we would have the following PJ.CFG:
-,makefile,,.obj \,$(MARK_1),.cpp,.asm,.c
-,makefile,, + ,$(MARK_2),.cpp,.asm,.c
+,.mak,,.obj \,$(MARK),.cpp,.asm,.c,.cas
+,.bld, + , &,,.cpp,.asm,.c,.cas
*,.obj
*,.err
Line 1 When you extract a file, modify the file
MAKEFILE every time a .CPP, .ASM, or
a .C file is extracted. After the first
occurrence of $(MARK_1) in MAKEFILE,
on the next line, insert the file name being
extracted with no prefix and with a:
.obj \
suffix.
Line 2 When you extract a file, modify the file
MAKEFILE every time a .CPP, .ASM, or
a .C file is extracted. After the first
occurrence of $(MARK_2) in MAKEFILE,
on the next line, insert the file name being
extracted with no prefix and with a:
+
suffix.
Line 3 When you place a new file (with a .cpp,
.asm,.c,.cas extension) back in the library
(by specifying the path and extension),
modify the library_name.mak file as
follows: After the first occurrence of
$(MARK_1) in library_name.mak file, on
the next line, insert the file name being
extracted with no prefix and with a:
.obj \
suffix.
Line 4 When you place a new file (with a .cpp,
.asm,.c,.cas extension) back in the library
(by specifying the path and extension),
modify the library_name.bld file as follows:
At the beginning of the file, insert the file
name being extracted with a + prefix and
with an & suffix.
Line 5 When a replace operator is used with
FILENAME, delete the FILENAME.OBJ
file in the local directory.
Line 6 When a replace operator is used with
FILENAME, delete the FILENAME.ERR
file in the local directory.