Sibyl Libraries & Applications - HOWTO ====================================== Copyright 2003-2006 Aaron Lawrence Copyright 2006-2019 Ronald Brill Copyright 2019-2023 Alex Taylor 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 with Sibyl. Aaron has 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. (There were apparently problems with Sibyl Fixpack 4 and so it is not used, although some of the bug fixes from FP4 are included.) Your directory structure should look like ae source code for the AE program build output directory for built files ConfigApps source code for the ConfigApps program Components Sibyl components used by these applications 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 install program used by NewView Library library functions used by both applications and components NewView the NewView source code Sibyl updated Sibyl libraries (based on fixpack 3) unittests Some tests used by NewView Required Tools -------------- - Speedsoft 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. Setting Up the Build -------------------- 1. Copy `env.inc.sample` to `env.inc` and adjust the definitions as indicated in the file. 2. Adjust directories in the .spr (Sibyl project) files. Sibyl unfortunately requires absolute paths in several places in its project setup files. To avoid committing working-copy-specific configuration to the repository, templates are provided, along with a script to generate the working project files from them. From the top-level directory, run `project-setup.cmd`. This will create the .spr files in each directory. Alternatively, you can also generate the project files manually yourself. This can be done by copying each of the following files to the indicated filename, and then replacing every instance of `@NV_DEV@` in the new files with the full path of your working copy's top level directory. ae\ae.spr.def --> ae\ae.spr Components\Components.spr.def --> Components\Components.spr ConfigApps\ConfigApps.spr.def --> ConfigApps\ConfigApps.spr installer\NewViewInstall.spr.def --> installer\NewViewInstall.spr Library\ACLTest.spr.def --> Library\acl_build.spr Library\acl_build.spr.def --> Library\acl_build.spr NewView\NewView.spr.def --> NewView\NewView.spr NewView\viewstub.spr.def --> NewView\viewstub.spr unittests\NewViewTests.spr.def --> unittests\NewViewTests.spr 3. Open a command line window and do the following: Change to directory `Sibyl`. Execute `makeall.cmd` Change to directory `Library'. Execute `makeall.cmd` Change to directory `Components`. Execute `makeall.cmd` 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. Build notes for the individual projects are below. Building Components ------------------- The Components project (`Components\Components.spr`) contains the updated Sibyl controls used by NewView and other projects (including custom ones such as the rich text viewer). For the Sibyl IDE to be able to use these classes, they are compiled into `CompLib.DLL`. When building applications like NewView, however, the object files will be linked statically into the application. The `makeall.cmd` script in the `Components` directory will rebuild all the object files (and the test app, `Components.EXE`. To rebuild `CompLib.DLL`, load `Components.spr` in the Sibyl IDE and rebuild it. *Note:* Because the IDE requires `CompLib.DLL` to actually load a project using those classes, and the Components project includes a demo form with the classes on it, this rather unintuitively means that you can't build `CompLib.DLL` unless a previously-built `CompLib.DLL` already exists. For this reason, a prebuilt version with all the new/modified classes is included in this repository. Building NewView ---------------- Make sure steps 1-3 above have been completed. You should be able to build NewView.EXE and ViewStub.EXE with debug symbols from a command line by running `makeall.cmd` in the `NewView` directory. Do not do this for a release version. To build a release version, you should build the executables from the GUI. When doing this, make sure that the directories `build\newview` and `build\newview_stub` exist and are writable. To build NewView.EXE from the GUI, open the project file `NewView\NewView.spr` from the Sibyl IDE. You should be able to build it from the Project menu. NewView.EXE will be placed in the `build\newview` directory. *Note:* If you get errors about classes not being found, or CompLib.DLL unable to be loaded, make sure that CompLib.DLL exists in the directory indicated in `NewView.spr` - this _must_ be the version of CompLib.DLL from this project, and _not_ the default one shipped with Sibyl. See the section above for details. You can build ViewStub.EXE from the GUI in the same way as NewView.EXE, by opening `NewView\ViewStub.spr` in the IDE and building it from the Project menu. Turn debugging symbols OFF (in project settings) when building it. ViewStub.EXE will be placed in `build\newview_stub`. ### HelpMgr DLL ### Go to the `hlpmgr` directory and run `makeall.cmd`; helpmgr.dll will be placed in the `build\hlpmgr` directory. Alternatively, if OpenWatcom is available in PATH, INCLUDE, and LIB, you can run `wmake` directly. However, note that the Watcom C makefile for HelpMgr will build hlpmgr2.dll by default. To build helpmgr.dll instead, build with `wmake helpmgr.dll` (which `makeall.cmd` does). 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. ### NewView DLL ### Go to the `newview_dll` directory and run `makeall.cmd`. Or, if OpenWatcom and PMPrintF are already installed and available in PATH, INCLUDE, and LIB, you can simply run `wmake` directly. ### Help & Language Files ### The NewView help file was is in .ipf format and can be compiled with the OS/2 IPFC compiler. The language files use Aaron's language support module (see `NewView\Design.txt` for technical information) and are simply structured text files. Run `makeall.cmd` from the `i18n` directory to build/copy all the help and language files. Each language lives in a subdirectory with its own `makeall.cmd` that gets called by the parent script. ### Install EXE ### This is another Sibyl project that can be opened in the IDE and compiled. It is the old standalone installer for NewView. The project will create the executable NewViewInstall.EXE - you are recommended to rename it to install.exe if you need distribute it as part of a NewView installation ZIP file. Make sure steps 1-3 above have been completed. Also make sure the directory `build\installer` exists and is writable. The install executable requires Aaron's renmodul.dll, a copy of which is in the `installer` directory (the sources are not included here, but are available on Hobbes and elsewhere). I expect there should be little need to change this in the future. ### Building an Installation ZIP File ### Pull together these files into a ZIP: newview.exe (from build\newview) viewstub.exe (from build\newview_stub) newview.dll (from build\newview_dll) helpmgr.dll (from build\hlpmgr) install.exe (from build\installer, rename from NewViewInstall.EXE) renmodul.dll (from installer) (language files) (from build\newview_i18n) Things to do before releasing: see `NewView\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 Building ConfigApps ------------------- Make sure steps 1-3 above have been completed. Also make sure the directory `build\ConfigApps` exists. Open the project file `ConfigApps\ConfigApps.spr` in the Sibyl IDE. You should be able to build it from the Project menu. ConfigApps.EXE will be placed in the `build\ConfigApps` directory. Building AE ----------- Make sure steps 1-3 above have been completed. Also make sure the directory `build\AE` exists. Open the project file `ae\ae.spr` in the Sibyl IDE. You should be able to build it from the Project menu. AE.EXE will be placed in the `build\AE` directory. To build and copy the language files, run `makenls.cmd` in the `ae` directory. ### Building an Installation ZIP File ### Pull together these files into a ZIP: ae.exe (from build\ae) * (from build\ae_i18n) As with NewView, convention for ZIP files is `aeA_B_C.zip` for version A.B.C. Old Notes from Aaron -------------------- The following are left over pieces from Aaron's original build notes. They should not be needed anymore, but are included for posterity. -- 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. 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.