arch.gml

开放源码的编译器open watcom 1.6.0版的源代码

.id sys_windowed
= 1. If creating a DLL, set
.id sys_dll
= 1. Delightfully simple.


.section Include Paths
.*
.np
.ix 'include paths'
The
.id inc_path
macro is composed of several other variables.
Projects are able to hook any of these variables by redefining them after
.us cproj.mif
is included. The current structure looks like this:
.millust begin
inc_path      = inc_dirs | inc_dirs_$(host_os) | inc_dirs_sys
inc_dirs_sys  = inc_dirs_lang | inc_dirs_sys_$(host_os)
inc_dirs_lang = $(lang_root)\h
.millust end
So, a project should put any include directories it needs into
.us inc_dirs
&mdash note that this does not include
.id $(watcom_dir)\h
which is part of the default include directory set.
.np
If it needs to, a project can override any and all of these &mdash for instance,
the clib needs to be built with the next release header files, and so would
redefine
.id inc_dirs_lang.
.np
Any OS-specific header files needed by the project can be set in
.id inc_dirs_$(host_os)
&mdash again, this should not include the standard system
header files, which will be defined in
.id inc_dirs_sys_$(host_os).
.np
Note that the build system previously used to set the
.id INCLUDE
environment variable to hold the contents of
.us inc_dirs
macro. This mechanism is now considered obsolete and should no longer used.
Instead, include paths are passed directly on the command line. This also
means that all include paths must be prepended with a -I switch, for example:
.millust begin
inc_dirs_sys_nt    = -I$(lang_root)\h\nt
.millust end

.section Executive Summary
.*
.np
.ix 'summary'
In order to convert a project to this new structure or create a new (and
conforming) project, do the following:
.np
.autonote
.note
Create an object file directory for each combination of host_os/host_cpu
under your project.
.note
Give your project a name, for instance Foo.
.note
Create a
.us master.mif
in the root of your project.
.note
Put all the normal makefile gear in this
.us master.mif.
.note
Add
.id proj_name
 = Foo to the top of master.mif
.note
Include the following files (in this order)
.us cproj.mif, defrule.mif, deftarg.mif
in
.us master.mif
.note
Add
.id inc_dirs
= {list of directories, separated by spaces and each prepended with -I,
which your project needs in include path - this does not include
OS-specific includes (ie
.us \lang\h\win
)}
.note
Add
.id extra_c_flags
= {list of c flags, not including optimization, -w4, -zq. -we and memory model info,
needed to compile your application} These should be host_os/host_cpu independent.
.note
Add
.id extra_l_flags
 = {list of linker directives, not incuding system or debug directives}
 Should be host_os/host_cpu independent.
.note
Use following to compile:
.id $(cc) $(cflags)
filename etc...
.note
Use following to link:
.id $(linker) $(lflags)
file { list of obj files }
.note
Use following to create libraries:
.id $(librarian)
.note
In each object file directory, create a makefile which looks like the following:
.millust begin
#pmake: build os_X cpu_Y
host_os  = X
host_cpu = Y
!include ..\master.mif
.millust end
.endnote
.np
That's it! The only downside is that sticking to these guidelines will make
everyone's life less exciting.


.chap Technical Notes
.section 32-bit Windows run-time DLLs
.*
.np
.ix 'Windows DLLs'
Most of Open Watcom run-time Windows DLLs have predefined loading address.
Bellow is table with address for each DLL.
.millust begin
0x69000000  wppdxxxx.dll  (C++ compiler)
0x69400000  wccdxxxx.dll  (C compiler)
0x69800000  wrc.dll       (Resource compiler)
0x69900000  wr.dll        (Resource library)
0x69c00000  wlink.dll     (Linker)
0x6a000000  wlib.dll      (Librarian)
0x6e800000  javavm.dll    (Debugger DIP)
0x6e900000  all trap dlls (Debugger TRAP)
0x6eb00000  madx86.dll    (Debugger MAD)
0x6ec00000  export.dll    (Debugger DIP)
0x6ed00000  codeview.dll  (Debugger DIP)
0x6ee00000  watcom.dll    (Debugger DIP)
0x6ef00000  dwarf.dll     (Debugger DIP)
0x6fa00000  wrtxxxx.dll   (run-time DLL combined C, math and C++ library)
0x6fd00000  plbxxxx.dll   (run-time DLL C++ library)
0x6fe00000  clbxxxx.dll   (run-time DLL C library)
0x6ff00000  mtxxxx.dll    (run-time DLL math library)
.millust end
You shouldn't use these addresses for your own DLLs.

.chap Build Process

We use the (Open) Watcom C/C++ compilers and Watcom
.us wmake
to build our tools, but at the top level we have a custom tool which oversees
traversing the build tree, deciding which projects to build for what platforms,
logging the results to a file, and copying the finished software into the
release tree (rel2), making fully automated builds a possibility. If nothing
goes wrong that is.

.section Builder
.*
.np
.ix 'builder'
This wondrous tool is called
.us builder.
You can see
.us bld\builder\builder.doc
for detailed info on the tool and/or look at the source if the documentation
doesn't satisfy you.
.np
So how does builder work? Each project has a
.us lang.ctl
builder script file. If you go to a project directory and run builder, it will
make only that project; if you go to
.us bld
and run builder, it will build everything under the sun. The overall build uses
.us bat\lang.ctl
which includes all of the individual project
.us lang.ctl
files that we use. Note that if you run builder, it will traverse directories upwards
until it finds a
.us lang.ctl
(or it hits the root and still doesn't find anything, but then you must have
surely done something wrong). Results are logged to
.us build.log
in the current project directory and the previous
.us build.log
file is copied to
.us build.lo1.
The log file contains captured console output (both stdout and stderr).
.np
Common commands:
.begnote
.note builder build
&mdash build the software
.note builder rel2
&mdash build the software, and copy it into the "rel2" release tree
.note builder clean
&mdash erase object files, executables, etc. so you can build from scratch
.endnote

.section Pmake
.*
.np
.ix 'pmake'
Many of the projects use the "pmake" features of builder (see
.us builder.doc
) or standalone pmake tool. If you want to see its guts, the
.us pmake
source is in
.us bld\pmake.
.np
Each makefile has a comment line at the top of the file which is read by
.us pmake.
Most of our
.us lang.ctl
files will have a line similar to this:
.millust begin
pmake -d build -h ...
.millust end
this will cause
.us wmake
to be run in every subdirectory where the makefile contains
.id "build"
on the
.id #pmake
line. See for instance the C compiler makefiles (in
.us bld\cc)
for an example.
.np
You can also specify more parmeters to build a smaller subset of files. This
is especially useful if you do not have all required tools/headers/libraries
for all target platforms.
.np
For example:
.millust begin
builder rel2 os_nt
.millust end
will (generally) build only the NT version of the tools.
.np
A word of warning: running a full build may take upwards of two hours on
a ~1GHz machine. There is a LOT to build! This is not your ol' OS kernel
or a single-host, single-target C/C++ compiler.
.np
It is generally possible to build specific binaries/libraries by going to
their directory and running
.us wmake.
For instance to build the OS/2 version of
.us wlink
you can go to
.us bld\wl\os2386
and run
.us wmake
there (note that the process won't successfully finish unless several
required libraries had been built). Builder is useful for making full
"release" builds while running
.us wmake
in the right spot is the thing to do during development.
.np
Happy Building!


.chap Testing
.*
.ix 'testing'
There is undoubtedly a question on your mind: Now that I have the Open Watcom
compilers, libraries and tools built, what do I do next? The answer is simpler
than you may have expected: Ensure that what you built actually works.
.np
Fortunately there is a number of more or less automated test available in the
source tree. Currently these tests are not part of the build process per se,
although that might (and perhaps should) change in future.
.np
There are two major classes of situations when the tests should be run:
.begbull
.bull
After building on a fresh system for the first time, running (and passing)
the tests verifies that what was built behaves at least somewhat as expected.
In this case it might be prudent to run as many tests as possible, especially
when building on a new, not yet widely tested platform.
.bull
After making modifications to a particular tool or library, run the
appropriate tests exercising the component (if available) to ensure that the
changes didn't cause any serious regressions.
.endbull
.np
If a bug is discovered and fixed, it is a good practice to code up a simple
test verifying the fix. That way we can prevent (or at least expediently
discover) regressions in future builds. In other words, we won't be embarrassed
by the same bug cropping up again. Just because commercial compiler vendors
occasionally have this problem doesn't mean we have to as well!
.np
Passing the automated tests can never completely guarantee that everything
works perfectly as designed, but it does let you sleep easier at night,
comfortable in the knowledge that there aren't any really major problems.

.section Running the tests
.*
.np
This section maps the major test nests and gives brief description on how
to run the tests and how they're constructed. There is often a single batch
file or script that will build and run all the tests for a given project,
the end result being either "all set to go" or "we have a bug infestation
problem at location xyz, send out bug swat team immediately".
.np
To make automated testing feasible, the test programs do not require user
input (unless they were testing user input of course). Some test programs do
their work and then decide whether everything worked as expected or not and
output a message to that effect. Other test programs ouput messages mapping
their progress as they go and the output is then compared with a file
containing the 'good' output. Which method exactly is used depends mostly
on what is being tested. When testing error and warning messages
printed by the compilers and tools, it is natural to compare the captured
output to the expected text. When testing the runtime library for instance,
it makes sense for the test program itself to decide whether the function
call results are what was expected.
.np
Now we'll go through the projects alphabetically and make a stop whenever
there's something interesting to see. Note that not all of the tests are
automated, the really extensive tests are however. Being a lazy folk,
programmers are likely to bang together an automated test suite if that
helps them avoid babysitting the tests.
.begnote
.note as
In
.us bld\as\alpha\test
there are several tests exercising the Alpha AXP assembler, using C wrappers
for infrastructure.
.note aui
Not a real test, nevertheless the sample programs in
.us bld\aui\sample
are useful in demonstrating and informally testing the user interface library.
.note brinfo
In
.us bld\brinfo\test
there is a simple browser information test program.
.note browser
Tests exercising the class browser are located in
.us bld\browser\test.
.note cg
In
.us cg\test\far16
there is a test exercising the
.id __far16
keyword. Real code generator tests are found elsewhere.
.note clib
The C runtime library tests are located in
.us bld\clib\qa.
These tests are not terribly comprehensive but they do verify the basic C
runtime functionality.
.note gui
Again not a real test, there is a GUI library sample in
.us bld\gui\sample.
.note ndisasm
Tests for the 'new' disassembler (not many at this point) are located in
.us bld\ndisasm\test.
.note orl
The Object Reader Library tests are in
.us bld\orl\test.
.note plustest
This project holds
.us the
test suite. Ostensibly designed to exercise the C++ compiler, the tests also
verify the functionality of the code generator and some are designed for the
C compiler. Running these tests can take a while as there are over a thousand
test cases. Highly recommended.
.note ssl
In
.us bld\ssl\test
there are several simple test scripts for SSL.
.note trmem
While the memory tracker is not a test, it bears mentioning here. This can be
used for testing many other projects for memory leaks, memory overwrites and
other cases of rude behaviour.
.note viprdemo
Again not a test per se, the 'Viper demo' is a good way to verify basic IDE
functionality.
.note wasm
Extensive assembler test can be found (rather predictably) in
.us bld\wasm\test.
.note wdisasm
Tests for the 'old' disassembler are located in
.us bld\wdisasm\test.
.note wmake
Extensive make utility tests can be found in
.us bld\wmake\reg
and
.us bld\wmake\regress.
.note wprof
A profiler test program is located in
.us bld\wprof\test.
.note yacc
Several sample/test YACC input files are in
.us bld\yacc\y.
.endnote