[M3devel] Looking to update cm3 manual page.

[Randy Coleburn]

Peter:
 
We need to make sure to add information about cm3IDE.
 
The users guide can be found at:  m3-sys\cm3ide\UsersGuide\CM3_IDE_UsersGuide.pdf
 
Some of the environment variables you describe have to do with cm3IDE.
 
Here is a list:
 
CM3_IDE_HOME = env var for root of home folder
HOME = alternate home folder root, if CM3_IDE_HOME not supplied
 
The following variables are expected to be defined in the CM3.CFG file:
 
INITIAL_CM3_IDE_BROWSER = full path to the web browser that should be used with cm3IDE
INITIAL_CM3_IDE_EDITOR = full path to the text editor that should be called by cm3IDE
BUILD_DIR = NT386, HPPA, etc.
PKG_USE = full path to the public package root, e.g. /cm3/pkg
DOC_INSTALL = full path to the documentation root, e.g. /cm3/doc
 
If the first 2 are not defined, cm3IDE will prompt user on command line to provide these the first time it is run.  Thereafter, it saves the information in its config file that it places in the CM3_IDE_HOME folder.
 
If the last 3 are not defined, cm3IDE tries to construct them using heuristics.  If not successful, the program will abort.
 
cm3IDE requires that is "examples" folder be located off the installation root, e.g., cm3/examples.  If examples is not found, cm3IDE will still run, but it will not be able to offer up any examples.
 
In an environment that allows spaces in filenames, such as Windows, you can run into problems if any of the paths defined in these variables have embedded spaces.  On Windows, you can get around this problem by using the short 8.3 name equivalent.
 
Regards,
Randy

>>> Peter Eiserloh <eiserlohpp at yahoo.com> 12/2/2009 12:01 PM >>>
Hi all,

It has been more than half a year since I last looked at the
CM3 manual page.  I am now looking at the it in preparation 
for the release of version 5.8, and noticing some deficiencies.

I asking for help in identifying any further places it is lacking.
I can integrate any feedback into a revised manual page, and
submit an updated version back to the archives.


Currently identified deficiencies: 

o The manual page should explicitly state which version of the
  compiler it documents.

o The sub-section "Expected Directory Structure" needs a better
  discussion, especially an introduction.

o The discussion of mode option "-ship" mentions environment
  variable CM3_INSTALL_ROOT, yet in cm3.cfg we set INSTALL_ROOT
  without the  "CM3_" prefix.  This should be resolved.

  ** What is the exact meaning of these two?  Is one recognized
     by the compiler, and the other by the supporting quake
     code?

o The ENVIRONMENT section does not mention CM3_INSTALL_ROOT
  at all.  Add a discussion about both INSTALL_ROOT, and
  CM3_INSTALL_ROOT.

  ** Am I missing any other environment variables?

o Missing command line options for the compiler:

  - I currently have "-g", but no discussion of -gstabs.
    No discussion about not supporting DWARF (or do we?).

o Compiler unique language features, (i.e., pragmas).  The
  reference books (Nelson, and Harbison) give a list of 
  suggested pragmas.  The manual page should list the ones
  supported by the CM3 compiler explicitly, and show their
  syntax.

  ** Can someone list for me the pragmas supported by the
     current (5.8.4) compiler.

o Should list any limitations of either the compiler, or
  the library suite provided with the compiler.  

  For example, the WIDECHAR is limited by its 16-bit size
  to only a portion of the unicode character set 
  (the basic multi lingual plane), whereas a unicode 
  character is 20-bits, and we would need either a 
  24-bit or 32-bit sized type to contain it all.

  ** Are there any other known limitations of the compiler,
     or library suite?
       - length of identifier?
       - length of TEXT (ie, memory)
       - length of filenames, or pathname 
         (some architectures may have differences, 
         ie MS-Windows).

o There should be a discussion of the @m3XXX runtime
  library command line options.

o There should be an EXAMPLE section, with example 
  source code (Hello world), along with supporting 
  m3makefile.


+--------------------------------------------------------+
| Peter P. Eiserloh                                      |
+--------------------------------------------------------+


      
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://m3lists.elegosoft.com/pipermail/m3devel/attachments/20091202/d3e1ca17/attachment-0002.html>