INTRODUCTION ------------ This file is about all the help you get, when trying to compile Maximus. We were strapped for time before the 1.02 release, so we didn't get a chance to make this as pretty as we wanted it to be. Then again, if you're reading this, it's a fairly good assumption that you're at least semi-technically-competent, and know what you're doing. For this reason, I won't go into the `idiot-proof' detail that you'll see in the Maximus executables and documentation. But first: vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv >>>>>>>>>>> READ THE LICENCE BEFORE USING THESE FILES! <<<<<<<<<<<<<<<< ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ There are several VERY important items contained in the licence (stored in LICENCE.MAX), including the naming convention for modified versions, restrictions on the use of this source, and use in a commercial environment. You are not granted the right to use anything in this package until you have read the license. Yes kids, YOU HAVE TO READ EVERY SINGLE WORD OF IT. If this source is misused because others are ignoring the licence, then not only will I talk unkindly about you, but I may also have my lawyer give you a call. In short: read the licence, so that you don't screw it up for both yourself and everyone else. Now, on a lighter note: TOOLS REQUIRED -------------- TO RECOMPILE MAXIMUS USING TURBO C, you'll need the following programs: - TC 2.0 or TC++ 1.0 - TLINK 2.0 (or above) - LIB 3.0 (or above). (You can use Borland's TLIB instead, if you aren't making a version of Max with overlays. However, you'll have to change \TC\MAX\SLIB\MAKEFILE, by setting "LIB = tlib" instead of "LIB = lib".) - Either TASM (1.0 or above) or MASM (5.0 or above). However, the object files come precompiled. See below for details.) - NDMAKE (see `Where to get NDMAKE', later in this document) TO COMPILE A VERSION OF MAXIMUS WITH OVERLAYS (still using Turbo C), you'll also need: OVLM6L.OBJ, extracted from the MSC 4.0 (yes, 4.0) RTL Microsoft Overlay Linker, version 3.0+ IF YOU HAVE TC++, which includes internal overlay support, then you may be able to get it to work, without any of the above two items. However, I haven't tried this, so no guarantees. TO COMPILE MAXIMUS USING MICROSOFT C, please refer to the enclosed MSC_READ.1ST file. Most of the information which follows pertains to Turbo C only -- however, you SHOULD at least read the next section, which is what tells you where to put all of the silly .LZH files. In addition, to compile Maximus using any compiler, you'll also need DOS version 3.1+. MAXS_102.LZH ------------ MAXS_102.LZH contains a number of nested LZHchives. Although all of the makefiles and batch files are completely generic, it is recommended that you set up the following directory structure: \TC\MAX - Where all .EXEs and batch files are placed \TC\MAX\MAX - Source for Maximus itself \TC\MAX\PROT - Source for the BinkleyTerm protocol code \TC\MAX\UTIL - Miscellaneous utilities, such as PIPER, SILT, MECCA, etc. \TC\MAX\SLIB - Miscellaneous routines from Scott's private library (If you're compiling under OS/2, you can run MSC_UNP.CMD to unpack everything automatically.) In addition, you should also create the following directories: \TC\MAX\MAX\R \TC\MAX\MAX\OR \TC\MAX\PROT\R \TC\MAX\UTIL\R \TC\MAX\SLIB\R\S \TC\MAX\SLIB\R\M \TC\MAX\SLIB\R\C The compilation batch file will try to create these if they don't exist, but it's safer to do it yourself. The above six directories are used for holding the object files generated by your compiler. (The 'R' stands for REAL mode, as opposed to 'P' for protected or OS/2 mode. The 'S', 'M', and 'C' stand for memory models, since the SLIB routines need to be compiled in all of the SMALL, MEDIUM and COMPACT memory models.) Although you can rename the main directories, the object files will ALWAYS go into a subdir off the main directories you specify. In other words, if you want to use '\TC\BBS\UTIL' instead of '\TC\MAX\UTIL', you'll still need to create '\TC\BBS\UTIL\R' to hold the object files. Once you have created the directory structure, you must then place the files into the appropriate places. Assuming that you've used the default directory structure, you should decompress the *.LZH files into the following directories: S_BATCH.LZH -> \TC\MAX S_MAX.LZH -> \TC\MAX\MAX S_PROT.LZH -> \TC\MAX\PROT S_UTIL.LZH -> \TC\MAX\UTIL S_SLIB.LZH -> \TC\MAX\SLIB MAKE SURE TO PUT THE \TC\MAX DIRECTORY AS THE **FIRST** ITEM ON YOUR 'PATH', AND MAKE SURE THAT BOTH MAKE.INI AND MAKE.EXE (THE FILE PROVIDED BY NDMAKE) ARE IN THIS DIRECTORY! If you don't put MAKE or some of the other files in this directory, or if that directory isn't the first item on your path, then you'll probably have some problems processing the source code. (Symptoms for having done this incorrectly include seeing Borland's MAKE banner [which the batch file never calls -- it only uses NDMAKE], or seeing lots of syntax errors in the makefiles.) In addition, make sure to copy the provided TURBOC.CFG into the SAME DIRECTORY WHICH YOU START TCC FROM! Unless you do this, you'll probably get several dozen error messages, mainly relating to files which couldn't be found. If you're using Turbo C, also make sure to read everything in this file. You may get nailed if you don't follow these instructions exactly. COMPILING MAXIMUS ----------------- Maximus was created using Borland's Turbo C and Turbo Assembler. However, Maximus should also compile cleanly under the DOS version of Microsoft C. (Microsoft users should now jump over to MAX_READ.1ST for compilation instructions.) Using Turbo C is probably the easiest way to recompile Maximus, since it's the compiler which I (Scott) use. However, note that you MUST use the command-line version, and not the integrated development environment. I haven't used the IDE for Maximus, and don't want to. (In other words, if you want to `IDEize' Maximus, you're on your own.) You'll find a file called TC.BAT in the \TC\MAX directory, which is a simple batch file which invokes NDMAKE in several different places. You'll also need to have the SMALL, COMPACT and MEDIUM memory models installed, for the TC run-time library. (Your Turbo C manuals should tell you how to install more memory models.) Once you have everything in place, the only thing left to do is to edit VAR.BAT and TURBOC.CFG, in the \TC\MAX directory. Simply change all of the path references to reflect your system configuration, for both of the files. (TURBOC.CFG contains the default settings for TCC.EXE. VAR.BAT is called by TC.BAT, to set up some defaults, which are then used in the makefiles.) Before starting the compile, make sure that you have removed all TSRs and other memory-hogging junk. TC is a memory hog too, and it needs at *least* 580K of FREE memory to build everything. Finally, simply type `TC' to start the compile process. If all goes well, NDMAKE should start building everything. Using Turbo C, the full compile process takes about 25 minutes on my 386/20 (no hardware memory cache, but with a 1 meg disk cache), so you can plan coffee breaks accordingly. If everything went according to plan, there should be no errors. None of the modules should produce any warnings, with the exception of the protocol code (which was originally written in Microsoft C.) All of the executables should be found in the \TC\MAX directory. You should end up with the following files: MECCA.EXE - the MECCA compiler ORACLE.EXE - the ORACLE file viewer ACCEM.EXE - the ACCEM decompiler SILT.EXE - the control-file compiler SCANBLD.EXE - the mail database updating util ANSI2BBS.EXE - the ANSI -> .BBS util ANSI2MEC.EXE - the ANSI -> .MEC util CVTUSR.EXE - the Opus/QBBS -> Maximus util EDITCALL.EXE - the call-number fudging util PIPER.EXE - the Opus 1.03/1.10 convert util MAXD.EXE - the debuggable version of MAX.EXE MAXN.EXE - the non-debuggable version of MAX.EXE. The default version of the makefiles do not build an overlay version of Maximus. However, if you have enabled the appropriate line in \TC\MAX\MAX\MAKEFILE, you may also see a file called `MAX.EXE', which is the version of MAX.EXE with overlays. (See below.) Although TC.BAT compiles everything, you may wish to compile only part of Maximus at one time. Depending on which directory you are currently in, the NDMAKE utility will do different things. --> NOTE: if you're not using TC.BAT, you MUST run \TC\MAX\VAR.BAT before using any of the commands below. VAR.BAT sets some variables which the makefiles need, and you won't have any luck building Maximus without it. IF THE CURRENT DIRECTORY IS \TC\MAX\MAX, you can type any of the following commands: MAKE - Build MAX*.EXE MAKE LINKN - Link non-overlay version of Maximus MAKE LINKD - Link debuggable version of Maximus MAKE LINKO - Link overlay version of Max (see below) IF THE CURRENT DIRECTORY IS \TC\MAX\UTIL, you can type any of the following commands: MAKE - Build all utilities MAKE MECCA - Build MECCA MAKE ACCEM - Build ACCEM MAKE SILT - Build SILT MAKE SCANBLD - Build SCANBLD MAKE ANSI2BBS - Build ANSI2BBS MAKE ANSI2MEC - Build ANSI2MEC MAKE CVTUSR - Build CVTUSR MAKE EDITCALL - Build EDITCALL MAKE PIPER - Build PIPER MAKE ORACLE - Build ORACLE IF THE CURRENT DIRECTORY IS \TC\MAX\SLIB, you can type any of the following commands: MAKE - Build all library memory models MAKE PVTLIBS.LIB - Build the SMALL memory model MAKE PVTLIBM.LIB - Build the MEDIUM memory model MAKE PVTLIBC.LIB - Build the COMPACT memory model IF THE CURRENT DIRECTORY IS \TC\MAX\PROT, you cannot type any MAKE commands. The MAKEFILE in \TC\MAX\MAX will automatically build all of the protocol code, so you must build the protocol code from there. CREATING AN OVERLAID VERSION OF MAXIMUS WITH TURBO C 2.0 -------------------------------------------------------- Compiling an overlaid version of Maximus under Turbo C 2.0 (see the next topic about TC++ and VROOMM) is, in a word, tricky. The biggest problem will be finding an overlay manager -- the recommended choice is the OVLM6L.OBJ module, extracted from the Microsoft C 4.0 (yes, 4.0) RTL. I'm told that the MSC 5.x and 6.0 overlay modules create some unresolved external references, so it would be best to use the MSC 4.0 version if you can. I'm also told that a shareware overlay manager, specifically one called "OVL", will work just as well, but I haven't seen it as of yet. You'll also need to find a copy of the Microsoft Overlay Linker. Although all versions of DOS come with a LINK.EXE, not all of them support overlays. Simply type in `LINK' at the DOS prompt, and read the first line of the banner displayed. If it doesn't say "Microsoft Overlay Linker", but rather "Microsoft 8088 Object Linker", or just "Microsoft Linker", then you have the wrong LINK. Suggested source: any of the Microsoft languages, such as MASM, MSC, QB, etc. Now that you have all of the required tools, try changing to the \TC\MAX\MAX directory, and type `MAKE LINKO'. (This tells MAKE to start up LINK.EXE, using the overlay response file.) If Microsoft's LINK appears to hang while linking Max for the first time, then you may have stumbled across one of the bugs which I did... Apparently, LINK doesn't like some of the new record types in the .LIB files which Borland distributes with TC. If LINK hangs, then the only way to fix it is to extract all of the library modules using TLIB, and rebuild the entire library (ouch!) using LIB. If that's too much work, then maybe you'll want to stick with the non-overlaid version... :-) If you want NDMAKE to automatically build the overlay version every time you enter `MAKE', without having to do an explicit `MAKE LINKO', then you must edit `\TC\MAX\MAX\MAKEFILE'. In the last third of the file, you should see a section of code which looks like this: tdstrip $(EXEDIR)\maxd.exe $(EXEDIR)\maxn.exe # link $(LINKOVL) To have NDMAKE automatically create the overlay version, simply remove the pound sign (the `#') before the `link' command. PUTT PUTT, VROOMM VROOMM, SPUTTER? ---------------------------------- If you're using TC++, the new Virtual Runtime Object-Oriented Memory Management (VROOMM) **might** work with Maximus. I borrowed someone else's TC++ for a week, and tried to VROOMM the Maximus object files (produced by TC 2.0), but it didn't work. (I think it has something to with the startup module... I tried fiddling with the TC 2.0 module, to make it more like the TC++ module, but it didn't work.) Of course, if you're compiling Maximus completely under TC++ (which supposedly produces worse code than TC 2.0, which is why I didn't try it), then you probably won't have any problems. But you get no guarantees... PRECOMPILED OBJECT FILES ------------------------ For the TC version of Maximus, I have taken the liberty of preassembling all of the *.ASM files, in case any of you don't have an assembler. You'll find an archive called S_OBJ.LZH, which contains two further nested archives: OBJ_S.LZH and OBJ_M.LZH. The files therein should be placed as follows: OBJ_S.LZH: XPUTCH.OBJ: \TC\MAX\SLIB\R\S\XPUTCH.OBJ DV_ASM.OBJ: \TC\MAX\SLIB\R\S\DV_ASM.OBJ OBJ_M.LZH SLEEP.OBJ: \TC\MAX\MAX\R\SLEEP.OBJ CALLFOS.OBJ: \TC\MAX\MAX\R\CALLFOS.OBJ MISC.OBJ: \TC\MAX\MAX\R\MISC.OBJ DDOSINST.OBJ: \TC\MAX\MAX\R\DDOSINST.OBJ DV_ASM.OBJ: \TC\MAX\SLIB\R\M\DV_ASM.OBJ XPUTCH.OBJ: \TC\MAX\SLIB\R\M\XPUTCH.OBJ After doing this, you should be able to rebuild everything without an assembler. PORTABILITY NOTES ----------------- What follows are just some notes which have been made over the course of Maximus' development: `\a' is an ANSI extension to K&R, which rings an A)udible bell on the console. (Control-G on a TTY) The set of numbers in your character set *must* be in a sequential order, and the first number must start with zero, and end with nine. ie. "0123456789". The actual location of these numbers in your character set does not matter, but they *must* be in that order. Also, capital letters fall under the same restrictions, although they aren't as critical. I don't think I've gone out of my way to be non-portable, but use caution when porting to a system where pointers and int's are not the same size. If you're having trouble, use EGREP to search for: "(int)|(char *)|(long *)|(void *)|>>|<<" and look for things to change in that area. You *must* also have a case-sensitive linker -- if you don't, you'll have to add a few #defines in MAX.H to change some of the names around, particularly the modem/console output functions. The key/lock system is internally based on the numbers 0-7, while externally based (ie. in the eyes of the Sysop) on 1-8. That means that calls to UserHasKey() should be in the range of 0-7, although the display on local console should be in the range of 1-8. The output of either Printf(), Lprintf(), or Mdm_printf() must always be less than 256 characters. It is your responsibility to make sure that this does not happen. The functions will trap any INPUT formatting string over 256 characters, but there's no guarantee that the output string will be shorter -- By the time that happens, memory will probably be too trashed to do anything about it. If you really need to change the default ...printf() length, look for MAX_PRINTF near the middle of MAX.H. LOCAL/MODEM OUTPUT FUNCTIONS ---------------------------- THis is just a quick-referenec guide to the Maximus input/output functions. Learning the difference between the different output functions is required for proper understanding of the source code. "translation" means the function translates AVATAR codes, and if the function is for local video output, it may write directly to the screen, depending on what the displaymode variable is set to. "formatted" means that the function can accept a variable number of parameters, and uses ?printf() translation characters. "raw" implies that the function will do the operation directly, with no translation of AVATAR control codes (ie. no nuttin'). For local video, the function may or may not use one of the enchanced video modes. lputc - output raw character to local console lputs - output raw string to console printf - output formatted string to console (always stdio) Lputc - output translation to local console Lputs - output string to console, with translation Lprintf - output formatted string to console, w/translation mdm_putcw - output raw character to modem mdm_puts - output raw string to modem mdm_printf - output formatted string to modem Mdm_putc - output translation to modem, w/carrier check Mdm_puts - output string to modem, w/translation and carrier checks Mdm_printf - output fmt'd string to mdm, w/xlation and carrier checks Putc - outp's char w/xlation and carrier check to console & modem Puts - outp's str w/xlation and carrier check to console & modem Printf - outp's fmt'd str w/xlation and carrier chk to con & mdm Where to get NDMAKE ------------------- NDMAKE is required to build the Turbo C version of Maximus. The make utility bundled with TC 2.x/TC++ is unusable for this type of application, so we have decided to use NDMAKE. If you don't already have NDMAKE, you can try calling an SDS (Software Distribution System) node, or either download or file-request NDMAKE itself (using the magic filename "NDMAKE") from the author's BBS, at 249/106. (Phone number: (613)389-8315.) - Scott Dudley August 7th, 1990 777 Downing St. FidoNet: 1:249/106 Kingston, Ontario IMEXnet: 89:483/202 Canada - K7M 5N3 InterNet: f106.n106.z1.fidonet.org ###