
- Paradigm Visual Make -
------------------------
C/C++/etc. software development environment

Copyright (C) 1998  Dan Miner		 dminer@nyx.net
Copyright (C) 1997  Andrew Guryanov	 andrew-guryanov@usa.net


I have volunteered to develop and maintain this software.  Please send
comments, suggestions, questions, and bug reports to dminer@nyx.net

You can find new versions of the software at:
	http://www.nyx.net/~dminer/pvm

Plans
-----
I plan on adding a number of new features to the editor such as syntax
highlighting.  The project manager needs to be expanded to handle mixed
language projects (common for me :) and adding file specific settings.
You can look forward to things as class/functions browsers, "error goto"
during compiles, and a more structure user interface.  And much, much more.

BTW, I'll be changing the program's name.

What's New?
-----------
* integrated small unreleased changes from Andrew
* quick change to the toolbar to look like Win 97 apps.
* fixed scrollbars positioning
* added simple undo/redo (unlimited, still alpha)

What is it
----------
PVM is software development environment, written on pure Tcl/Tk which
can be adjusted to different programming languages and source file types.

It incorporates a text editor, simple software project (makefile) editor
and enables you to develop and build your software projects from within
single program.  And for debugging your application, it can start your
favorite external debugger.

It also enables you to execute almost any external program (e.g. "diff" or
"dircmp") and capture its output into a specialised PVM text window.

It looks like a MS Windows MDI application and has highly reconfigurable
visual appearance.


What you should know
--------------------
You should have a good understanding of how software is usually built
on a UNIX system.  Such as:
	* how does "make" work
	* creating Makefiles by hand
	* be comfortable with your compiler's and linker's options
	* having used an archiver for libraries to good too

Hopefully, this will not be necessary in future releases.


System requirements
-------------------
To install and use PVM you need:
    --- UNIX + X-Windows environment;
    --- Tcl7.5 / Tk4.1 or higher
            try: "wish", or "iwish", or "itkwish"
            then, if it starts and you get "%" prompt,
            enter following commands:
                puts $tcl_version
                puts $tk_version
                exit
    --- "xlsfonts" program. I use it to enumerate known fonts.
            try "which xlsfonts".


How to install it
-----------------
1. Put all PVM files into a permanent location. (e.g. /usr/local/pvm).
2. Edit "pvm" shell script:
    --- change PATH_TO_WISH to the location of the "wish" binary
    --- change APP_HOME to the directory from step 1
3. Put "pvm" in your path (e.g. /usr/local/bin)

That is all. Now type "pvm" and press <Enter>.

BTW, you'll want to edit the docproj.res file to your system.


How to configure visual appearance
----------------------------------
You will see the main window if all goes well.  I like to use a dedicated
virtual desktop and maximized window.  Now, you can set the colors and fonts
by clicking Window->Preferences.

You will see a dialog with four button across the top (Fonts, Colors,
Positions, Predefined).  The options are pretty self-explanatory.
Predefined is lets you chose your fonts and colors from a set of predefined
"styles".  Your changes will be saved when you exit the application.

You can safely play in this area by clicking on the New tool button,
open the Preferences window, and use Apply to see the changes.  Everything
will be restored if you click Cancel in the Preference window.


Getting started
---------------
Press a couple of times left-most button in the toolbar or wait for the
tooltips, open or create a document.  To play with a "real" example, you
can File->Open (or Open tool button) sample.mak in $APP_HOME/sample.
Play with the project window, and the Project->Edit.  Maybe even
create a file, add it, and try using your function(s) from the original
program.  *grin*

Important Note:  Most commands apply to the active "window" in the
application.  Keep this in mind when you try Project->Build and
Project->Release.

[Rest of this pretty much Andrew's instructions]

How to edit text
----------------
All shortcuts and accelerators are specified in the Edit menu.
I'll write more about this later.

Note, that Find-Replace dialog is modeless. That is it works on
ACTIVE document and you can find given text in multiple windows -
one at a time, of course.


How to create/edit a project
----------------------------
Everything is better understood by example.

Select File->Open menu item and go to the directory where you have
installed PVM (was it /usr/local/pvm ?) double-click the "sample"
subdirectory and open "sample.mak" file.

Left mouse button double-click on any file in Project listbox opens
that file in a text window. Try also to hold down Shift or Control key
when clicking on a file...

Now select Project->Edit menu. You will see "Settings" dialog box.

Now, this is the place to say something about principles.
PVM uses some very general rules to create a makefile, namely:

   --- there are files that can be compiled by "Assembler"
   --- there are files that can be compiled by "Compiler"
   --- there are files that can be maked by "Maker" (nested makefiles!)
   --- both "Assembler" and "Compiler" produce "Object files" of the same format
   --- if "Target" is not empty, then all "Object files" should be "linked" by
       "Linker" or "archived" by "Archiver", depending on the type of the
       "Target"
       (if "Target" has archive-like extension - use "Archiver",
        otherwise - "Linker")
   
NOTES:
   --- when you press "Add directory" button, you should select then A FILE
       and press "Open", then ALL files in the given directory with the
       SAME EXTENSION will be added to the project.
   --- "General" flags are made to propagate throughout the "makefiles tree"
       that is why they should be used with care.
   --- if the target is an archive - you can use MORE THAN ONE makefile
       to contribute to it (archive)
   --- there are two SEPARATE build settings in each makefile - Debug and
       Release - be careful, edit BOTH of them.
   --- when the nested makefile is being build - it uses Release type settings
       only.  (I think it is convenient: e.g. Debug build can produce
       executable, while Release - a part of an archive).
   --- you can change Project default settings by editing "docproj.res" PVM
       source file

Now examine other makefiles: super1.mak, super2.mak, heap.mak.
I tried to demonstrate different types of build strategies and also a
flexibility of PVM.

Note, because all of them are about the same two C-files, either remove
intermediate object files manually between builds, or make rebuild.
Of course you can invoke build from command line too.

And finally look on "pvm.mak". It is a "makefile" for PVM itself.
It makes nothing of course, but gives easy access to all PVM files.
You can even "debug" PVM - press F5 key...

As I believe, all this gives enough freedom to adjust PVM to different
programming languages and to create your own customised development
environment.


Acknowledgements
----------------

Thanks to Andrew Guryanov for writing this program in the first place!

Thanks to Jeffrey Hobbs (http://www.cs.uoregon.edu/~jhobbs/). 
Under Tk4.1 I use his "Tk File Selection Dialog" (filesel.tcl).
Tk4.2 has standard one in the core...

Thanks to Stewart Allen (http://www.neuron.com/stewart/vtcl/).
Without his "Visual Tcl" this work was impossible.


-------------------
document revision:
    14 Jun 1998,  Dan Miner
    30 Jul 1997,  Andrew Guryanov
