Win32Forth

Building and saving an application

FSAVE, TURNKEY and APPLICATION all create new programs on your hard drive. They differ, in the type of program they create.

FSAVE

Creates a new copy of Win32Forth on your harddrive, that is a duplicate of the Forth you are already running, and will still start up running Forth when the new program is executed. FSAVE is followed by the name of the program to create. The name passed to FSAVE must not be the same name as the Forth program you are currently running. FSAVE is used as follows; 

FSAVE newforth <enter>

The amount of available dictionary space available will remain the same as before FSAVE was performed. If you need to change the amount of application dictionary or system dictionary space available for a subsequent program compile, you must perform a meta-compile by running META.BAT. It will prompt you for the new dictionary sizes.

TURNKEY

Creates an application program that cannot run Forth any longer, because all headers are discarded during the program save process. The 'cfa' of a forth definition that runs your program must be passed to TURNKEY. TURNKEY reduces the newly saved program image size by over 200k bytes. TURNKEYed programs cannot be debugged. TURNKEY is followed by the name of the program to create. The name passed to TURNKEY must not be the same name as the Forth you are currently running. TURNKEY is used as follows; 

' do-myprogram TURNKEY newprogram <enter>

TURNKEYed programs always have at least 3000 bytes of application dictionary space available at program startup, and zero bytes of system dictionary space available, since all of the system dictionary is discarded.

TURNKEY performs a default form of initialization defined above.

Your application word 'do-myprogram' as used above, is installed into the deferred word DEFAULT-APPLICATION by TURNKEY, so it will be run after initialization is completed. If you need to perform some other initialization than that shown above, then you will need copy the original definition of _DEFAULT-HELLO, change it and then install it into the deferred word DEFAULT-HELLO.

APPLICATION

Creates an application program on your harddisk that is also fully Forth. The 'cfa' of a forth definition that performs any needed program initialization must be passed to APPLICATION. APPLICATIONed programs can still be debugged. APPLICATION is followed by the name of the program to create. The name passed to APPLICATION must not be the same name as the Forth you are currently running. APPLICATION is used as follows; 

4000 4000 ' do-newapplication APPLICATION newapplication <enter>

where the first number was the bytes of application dictionary space you wanted to be available at program startup. The second number was the bytes of system dictionary space you wanted to be available at program startup. BOTH THESE VALUES ARE NOW IGNORED. APPLICATION is now effectively a synonym of FSAVE.

Internals

IMAGEMAN.F, IMAGERES.F and IMAGEHDS.F build Windows EXE images.

Supporting Documentation

For documentation on the PECOFF format, see http://www.microsoft.com/hwdev/hardware/PECOFF.asp. (Note: not included because of copyright restrictions, but freely downloadable.) Also see "Peering Inside the PE: A Tour of the Win32 Portable Executable File Format" by Matt Pietrek, and "An In-Depth Look into the Win32 Portable Executable File Format", same author, both findable on http://msdn.microsoft.com. There is very little documentation on the loader. An exception is "What Goes On Inside Windows 2000: Solving the Mysteries of the Loader" by Russ Osterlund, also from MSDN.

This quite complex code has 6 major parts.

  1. Field definitions using FLDBASE and FLD words.
  2. File handling for both .IMG and .EXE file words
  3. Section building and writing words
  4. Import library building and writing words
  5. Header building and writing words
  6. Resource generation (as of writing, still incomplete)

Example

DEFER CONTYPE ' GUI IS CONTYPE

: std-IMG2EXE ( addr len -- ) \ compose STD image, addr/len is name

	COMPACT \ compact header
	BUILD \ exe name

	CONTYPE EXE SUBSYSTEM \ normally GUI
	STD-LOADPOINT 		LOADPOINT
	0x100000 0xA000 	STACKSIZE
	0x100000 0x8000 	HEAPSIZE
	IMAGE-ENTRY 		ENTRYPOINT

	s" .code" SECTION
		STD-DATA STD-CODE or 		SECTIONTYPE
		IMAGE-CODEPTR IMAGE-CACTUAL 	SECTIONDATA
		IMAGE-CSIZE 			SECTIONSIZE
	ENDSECTION

	s" .app" SECTION
		STD-DATA 			SECTIONTYPE
		IMAGE-APPPTR IMAGE-AACTUAL 	SECTIONDATA
		IMAGE-ASIZE 			SECTIONSIZE
	ENDSECTION

IMAGE-SACTUAL IF \ might be a TURNKEY, so don't write section
	s" .sys" SECTION
		STD-DATA 			SECTIONTYPE
		IMAGE-SYSPTR IMAGE-SACTUAL 	SECTIONDATA
		IMAGE-SSIZE 			SECTIONSIZE
	ENDSECTION
THEN

	s" .idata" SECTION
		S-INIT S-READ OR 		SECTIONTYPE
		s" W32FCONSOLE.DLL" 		IMPLIB 
			0 s" c_initconsole" 		IMPORT
		s" KERNEL32.DLL" 		IMPLIB
			0 s" GetProcAddress" 		IMPORT
			0 s" LoadLibraryA" 		IMPORT
						ENDIMPORTS 
		SECTIONDATA
	ENDSECTION

	ENDBUILD
;

VIMAGE

IMAGEMAN has its own dictionary (because of possible name collisions) so a separate dictionary is used. 

COMPACT

Standard file is built with 4096 (0x1000) file sections. COMPACT specifies 512 (0x200) file sections, which builds a smaller EXE file at possibly the expense of slightly longer load times. 

s" name" BUILD

Identifies the new image name. 

X T SUBSYSTEM

where X is CUI (DOS application) or GUI | GRAPHICAL (Windows), and T is EXE or DLL 

n LOADPOINT

The loadpoint of the program (default is 0x400000). Must be aligned to a 64K boundary. 

n ENTRYPOINT

The (relative) entrypoint address in the section declared CODE 

N M STACKSIZE

The reserved and committed stack size. Default is 1Mb, 4K 

N M HEAPSIZE

The reserved and committed heap size. Default is 1Mb, 4K 

s" name" SECTION

The name of the section, case sensitive and 8 chars max.

n SECTIONTYPE    Section characterisics; default is none. Can appear multiple times for one section

S-EXECUTE

 section contains executable code

S-READ

 section can be read

S-WRITE

 section can be written

S-INIT

 section contains initialised data

STD-CODE

 is S-INIT S-CODE S-EXECUTE OR OR

STD-DATA

 S-INIT S-READ S-WRITE OR OR
N M SECTIONDATA is address and length of the section
N SECTIONRVA Not normally used, but can set the (relative) address of the section
N SECTIONSIZE Size of section. Must be equal to or longer than the sectiondata. When loaded, the section will zeroed and padded out to this length with zeros. Optional, set to size of the section data
ENDSECTION Required to end a section
s" implib" IMPLIB Import library name
N s" name" IMPORT Import the procedure <-name-> with a hint of N. N can be zero, but the correct hint will speed (marginally) load time.
ENDIMPORTS ( -- N M ) Required to end the imports sections, follow with SECTIONDATA
ENDBUILD Creates the image from the information given above.

Other words           

s" name" IMAGE-COPY

Copies the current executable for subsequent saving. Sets the following words as a side effect;      

IMAGE-PTR pointer to the loaded image
IMAGE-CODEPTR pointer to the code section
IMAGE-CACTUAL real size of code section
IMAGE-CSIZE virtual size of code section
IMAGE-APPPTR
IMAGE-AACTUAL
IMAGE-ASIZE		 ditto APP values
IMAGE-SYSPTR
IMAGE-SACTUAL
IMAGE-SSIZE		 ditto SYS values
IMAGE-ENTRY relative offset of entry point

 

Requirements/restrictions

Defaults

Building a turnkeyed application that runs without the console dll

See NoConsole

Document $Id: p-imageman.htm,v 1.2 2006/09/21 13:12:41 georgeahubert Exp $