source: trunk/howto.txt@ 401

NewView and libraries - HOWTO
-----------------------------

Copyright 2003-2006 Aaron Lawrence
Copyright 2006-2017 Ronald Brill


The major parts of the code are developed in SpeedSoft Sibyl.

Important Note:
  This setup will use these updated Sibyl libraries instead of
  the ones installed on your development PC. I (Aaron) have made many bug fixes
  and a few enhancements. Some things will not build with the original
  Sibyl Fixpack 3 libraries, for example some components depend on parts
  of the SPCC being changed from Private to Protected. I had problems
  with Sibyl Fixpack 4 and have not used it although some of the bug
  fixes from FP4 are included.


The whole dev environment uses hardcoded paths at some places. Because of this
you have to use NetDrive to place the code inside the directory

  P:\newview_dev

Your directory structure should look like

  P:\newview_dev
    build
    Components          Sibyl components used by NewView
    hlpmgr              replacement for OS/2 HelpMgr.dll
                           The HelpMgr DLL is compiled with Watcom C++.
                           It generates a DLL containing both 16 and 32 bit entry points,
                           like the original HelpMgr.dll.
                           See http://www.openwatcom.org.
    installer           NewView install program
    Library             library functions used by NewView itself and the components
    NewView             the NewView source code
    Sibyl               updated Sibyl libraries (based on fixpack 3)
    unittests

Building
--------

1. Required Tools

   Sibyl (FP 3)
       Make sure Sibyl (FP 3) is installed and working.
       You should be able to run spc20, the Sibyl command line compiler.

   OpenWatcom 1.5
       If you want to work on the HelpMgr.dll, make sure Watcom C/C++ is
       installed and working. You should be able to run wmake, the
       Watcom make utility.

2. Adjust directories in the .spr (Sibyl project) files.
  Sibyl uses absolute paths in its project setup files. Fix the location of your
  Sibyl installation.

3. Open a command line window and make P:\newview_dev the current directory
   execute env.cmd

   change to directory Sibl
   execute makeall.cmd

   change to directory library
   execute makeall.cmd

   change to directory Components
   execute makeall.cmd

4. Open the NewView project from the Sibyl IDE
   Open Newview in the Sibyl IDE, and you should now be able to compile it and change it.
   Conventionally, I compile the libraries (Sibyl, Library, Components) with debug information.
   You can then turn debugging on or off when compiling NewView itself; if debugging is off,
   the library debug info will be discarded at link stage.

   As for all useful Sibyl projects, optimisation CANNOT be used as it produces incorrect results.



















TODO

2. Unzip all files.


3. Adjust directories in the .spr (Sibyl project) files.

I have them set up so that they output the EXE, DLL and SPU (Compiled unit) files into subdirectories under D:\Temp\. They could equally well all go to the same directory.

Adjust the unit directories in each of the .spr files to match the output directories so that dependencies can be found.

You can do these adjustments either manually with a text editor or by loading the project files into the Sibyl IDE.

OutDir=D:\temp\newview
- this is where the EXE, DLL and SPU files go.

LibDir=D:\Temp\sibyl;D:\Temp\Library;D:\Temp\Components
- this is where Sibyl looks for SPU files when compiling (in addition to OutDir)

LibSrcDir=W:\sibyl\rtl;W:\sibyl\spcc;W:\components;W:\library
- this is where Sibyl finds source files when debugging (in addition to the project dir)

5. Run makelibs.cmd

This should build the Sibyl, Library and Components directories. Unfortunately, NewView itself cannot be compiled from the command line due to bugs in Sibyl.

The Library and Components directories could alternatively be loaded into the IDE and compiled if you want.

6. Install Components into Sibyl IDE

Before you can open the NewView project in the IDE (which is not essential, but likely to be helpful :), you will need to install each component used by NewView into Sibyl, so the the IDE can find them.

Use the Component - Install menu. Find the .spu file in question and click OK.

When installing components, Sibyl must be able to find all the SPUs of already installed components. This is the only time that the component directory setting matters. So make sure you update it to the output directory for the Components project.

The components are:
  In individual files (same name, without the T on the front):
    TCustomListBox
    TOutline2
    TCoolbar2
    TSplitBar
    TMultiColumnListBox

  In CustomFileControls unit:
    TCustomDriveComboBox
    TCustomDirectoryListBox
    TCustomFilterComboBox

  In ColorWheel unit:
    TColorWheel
    TValueBar

Yes, this is extremely tedious, and no there is no short cut as far as I know.

Other components can be installed or not as you see fit.

7. Open the NewView project

Open Newview in the Sibyl IDE, and you should now be able to compile it and change it.

Conventionally, I compile the libraries (Sibyl, Library, Components) with debug information. You can then turn debugging on or off when compiling NewView itself; if debugging is off, the library debug info will be discarded at link stage.

As for all useful Sibyl projects, optimisation CANNOT be used as it produces incorrect results.

HelpMgr DLL
-----------

The Watcom C makefile for HelpMgr will build hlpmgr2.dll by default.

You have to tell it to build helpmgr.dll instead, as makeall.cmd does, by typing wmake helpmgr.dll.

helpmgr.dll is normally in use by the WPS (WorkPlace Shell, the desktop) so to put it into use, you must either use a DLL-unlocking utility like replmod (on Hobbes.nmsu.edu) or boot to a command prompt, and replace the dll in c:\os2\dll.

Building hlpmgr2 is easier for debugging - you can then use the dllrname utility to modify existing executeables to use hlpmgr2 instead of helpmgr and therefore, you don't need to reboot to try your changes.

Install EXE
-----------

This is another Sibyl project that can be opened in the IDE and compiled.

I expect there should be little need to change this in the future.

Building an Install zip
-----------------------

distr.cmd in the NewView directory pulls everything together into a zip file that can be released. It runs E on a couple of files to remind me to update them :)

It moves files around rather confusingly, but basically it just pulls together these files:
  newview.exe
  helpmgr.dll
  install.exe
  readme.txt
  changes.txt
  gpl.txt

Things to do before releasing: see VersionUnit.pas.

Note: convention for ZIP files is
NewViewA_B_C.zip
for version A.B.C.

Underscores are more compatible than dots for certain broken bits of OS/2.

There is a template for uploading NewView zips to Hobbes.nmsu.edu

Help File
---------

The NewView help file was written with VyperHelp and the source for this is the NewView.vyd file. This is then exported to .ipf and can be compiled with the OS/2 IPFC compiler. This compilation is done in the distr.cmd file.

Bug/Todo List
-------------

TODO

You can find a list in versionunit.pas
There are also some bugs in the ecomstation bugtracker under newview, but I think they are all duplicated here.