File: palcom/doc/setup/Command-line-tools.txt

-------------------------------------------------------------------------------
Introduction 
-------------------------------------------------------------------------------

The PalCom developer tools can be invoked from the command line on
Windows, Linux and Macintosh (OSX).
These command line tools require a BASH shell to be executed.

On Linux and Macintosh, these are normally available with the standard
installation.

On Macintosh you run bash through the Terminal.

On Windows the tools depend on the Cygwin UNIX emulation to work.
See Cygwin-Install.txt for details on how to install and configure
this.
Some scripts can also be invoked in the standard Windows command
interpreter CMD.exe using BAT files.

-------------------------------------------------------------------------------
A. User tools
-------------------------------------------------------------------------------

The scripts placed in "palcom/bin" use precompiled, binary distributed
tools, and can thus can be used "out-of-the-box" for a freshly checked
out palcom directory.

They are:

  pal-vm[.bat]
    Invoke the binary distributed Palcom Virtual Machine. 
    Script command line options allows selecting between four
    different builds of the VM (Release, Debug, Checked, Profiling).
    Try "pal-vm -h"
  pal-j[.bat]
    Invoke the binary distributed Palcom Java Compiler. 
    Try "pal-j -help" or see palcom/doc/tutorials/pal-j
  pal-st[.bat]
    Invoke the binary distributed Palcom Smalltalk Compiler. 
    Try "pal-st -h" or see palcom/doc/tutorials/pal-st
  pal-asm[.bat]
    Invoke the binary distributed Palcom Bytecode Assembler. 
    Try "pal-asm -h"
  pal-dis[.bat]
    Invoke the binary distributed Palcom Bytecode Disassembler. 
    Try "pal-dis -h"
  pal-dep
    Invoke the binary distributed Palcom Component Dependency analyzer. 
    Try "pal-dep -h"
  pal-ovb
    Invoke the binary distributed Palcom Overview Browser. 
  pal-ass
    Invoke the binary distributed Palcom Assembly Assembler. 
    Type "help" at the "> " prompt to get a list of commands it handles.
  pal-launcher
    Invoke the binary distributed Palcom Assembly and Service Launcher. 

To use these scripts, simply add "palcom/bin" to your search PATH.
   
Here is a Cygwin alias that does it (assuming Palcom checked out in C:\):
     
   alias pal-setup='export PATH="/cygdrive/c/palcom/bin:$PATH"'

You can also set PATH through the standard Windows interface

   Start->Control Panel->System->Advanced->Environment Variables
   
A corresponding Linux or Macintosh alias, assuming palcom checked out
in your home directory:

   alias pal-setup='export PATH="~/palcom/bin:$PATH"'

To make a simple test of whether you have set up things correctly, try
invoking

   pal-root

which should simply print out the top directory of you palcom
checkout.

-------------------------------------------------------------------------------
B. Developer tools
-------------------------------------------------------------------------------

The scripts in palcom/bin/developer use the latest build of the tools
in palcom/developer, and as such requires pal-dev-build to be run
before being used. All developer scripts have names that
start with pal-dev-, and it is thus possible to have both the
developer-, and non-developer scripts in ones PATH. 

All scripts exists in BASH (for Linux/MacOSX/Windows Cygwin) syntax,
and a few of them also in CMD (.bat files for Windows) format.

These scripts include developer versions of all the "out-of-the-box"
scripts described above, as well as a number of other scripts:

  pal-dev-build
    Builds the basic code base including compilers, VM, base
    libraries, and core libraries. Use a number of other build scripts
    (not listed here) to build the various parts of the code base. 
  pal-dev-build-javadoc
    Rebuilds the javadoc in palcom/doc/javadoc from the current source
    files.
  pal-dev-clean
    Cleans the developer tree of all generated files
  pal-dev-test
    Executes various tests to ensure a consistent code base. This
    includes the tst and jtst unit tests, a number of test programs
    for the core libraries, all the tutorials in palcom/doc/tutorials,
    and (optionally) the benchmarks programs listed above.  
  pal-dev-export
    Makes an "export" of the current binaries in the developer tree
    into palcom/bin and palcom/lib. 

To use these scripts, add palcom/developer/dev-bin to your PATH as
described for the out-of-the-box scripts above.

Correspondingly, you can do a simple test of the setup by trying

   pal-dev-root

which should simply print out the top directory of you palcom
checkout.

If this works, you should be ready to invoke

   pal-dev-build

which builds all the basic elements of the palcom toolbox for you.