Working with the Dev Branch

How to obtain a copy of the current development revision

There are two source code "branches" in the git repository for ScarletDME. The first is called "master" and that's where the stable version of ScarletDME currently resides. Currently, (as of 01/27/22) the master branch will only build as a 32 bit target. The other branch is called "dev" and is where all the current development work is occurring.

The dev branch may contain untested features and code changes, so please be aware of potential breakage. The developers try their best to submit fairly stable code, but bugs will happen. If you are daring enough to try the latest code, please continue reading.

You can obtain the latest copy of the dev branch by using the below git command:

git clone --branch dev https://github.com/geneb/ScarletDME.git

I would recommend that you create a "scarlet-dev" directory and execute the git above git command from there.

If you find a bug, please check the current list of open issues and open a new issue if what you've found isn't already known. Feel free to add additional information to existing issues if you feel it would help.

The ScarletDME/info directory contains the change_log.txt file which outlines what has been worked on recently in the dev branch.

The notes.txt file in ScarletDME/info contains an ongoing list of things that are being examined, recent discoveries about the code, or general rambling.

How to build a new copy of ScarletDME from a fresh clone or pull

First, stop any instances of ScarletDME using "qm -stop". Please verify that qm is not running before you attempt to do any of this!

Build instructions can be found in ScarletDME/info/setup.txt - please make sure you've got gcc and make installed!

Note that if you run "make datafiles" that it could over-write any changes you've made to items in the QMSYS account!

You can edit the installed scarlet.conf file to include the parameters shown below. The primary thing is the ERRLOG directive, which sets the error log size to 100K.

[qm]
ERRLOG=100
QMSYS=/usr/qmsys
MUSTLOCK=0
NETFILES=0
NUMFILES=80
NUMLOCKS=100
NUMUSERS=40
OBJECTS=0
OBJMEM=0
SORTMEM=1024
SORTWORK=
TERMINFO=
DEBUG=4

Once you've got everything installed, you can start ScarletDME with:

sudo qm -start

Change to the /usr/qmsys/ directory and run 'qm -internal'. You will need to rebuild the GPL.BP sources, including the QMBasic compiler. The steps in this process should be strictly followed to avoid the possibility of breaking your QMBasic compiler and install. This is normally required only when SYSCOM.H is changed, but it is a good general habit to gain if you plan on building snapshots often.

After logging in using 'qm -internal', under /usr/qmsys/, rebuild the files in the following manner:

The CSRC VOC entry may already exist, so you may just need to change it.

Create a VOC entry for CSRC, pointing to the gplsrc directory under ScarletDME.

:ED VOC CSRC
New record
----: I
0001= F
0002= /your/path/to/ScarletDME/gplsrc
0003=
Bottom at line 2
----: FI
'CSRC' filed in VOC
:

If you need to edit the CSRC VOC entry, you can do so like this:

:ED VOC CSRC
VOC CSRC
2 lines

----: P
0001= F
0002= /your/path/to/ScarletDME/gplsrc
Bottom at line 2

----: R <path to your gplsrc directory>
0002: <path to your gplsrc directory>
Bottom at line 2

----: FI

'CSRC' filed in VOC
:

1) BASIC GPL.BP CPROC LOGIN BASIC BCOMP PTERM CATALOG

2) Exit out of QM

3) Log back into OpenQM again using "qm -internal"

4) BASIC GPL.BP *

5) Recompile any applications that need new features or changes provided by the new snapshot. It is best to recompile ALL of your application code if possible.

6) * * * Much Rejoicing * * *

How to upgrade an existing OpenQM GPL install from a snapshot

First, stop any instances of OpenQM using "qm -stop". Please verify that qm is not running before you attempt to do any of this!

If you do not want to include the distributed ACCOUNTS file, then delete the ./ACCOUNTS/ and ./ACCOUNTS.DICT/ directories from the unpacked tar files. If you do not remove these directories and copy everything to /usr/qmsys/ then you will overwrite your existing account configs.

After extracing the snapshot, simply build the distribution like you would the stable release.

You will need a C compiler and the 'make' system in order to build.

Run 'make' from the snapshot root to build the binaries. They will be located under ./bin/ after linking.

Once the binaries are built, copy ./bin/qm to either /usr/bin/ or another user binary directory listed in your environment path.

Copy everything except the ./gplsrc/ directory to /usr/qmsys/.

Run 'qm -start' to start OpenQM.

Change to the /usr/qmsys/ directory and run 'qm -internal'. You will need to rebuild the GPL.BP sources, including the QMBASIC compiler. The steps in this process should be strictly followed to avoid the possibility of breaking your QMBASIC compiler and install. This is normally required only when SYSCOM.H is changed, but it is a good general habit to gain if you plan on building snapshots often.

After logging in using 'qm -internal', under /usr/qmsys/, rebuild the files in the following manner:

1) BASIC GPL.BP CPROC LOGIN BASIC BCOMP PTERM CATALOG

2) Exit out of QM

3) Log back into OpenQM again using "qm -internal"

4) BASIC GPL.BP *

5) Recompile any applications that need new features or changes provided by the new snapshot. It is best to recompile ALL of your application code if possible.

6) If a system VOC upgrade has been included, then you should login to each account and allow it to upgrade the VOCs.

7) * * * Much Rejoicing * * *