1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
|
simpleDebugConsole readme
2007-10-06
BUILDING SIMPLEDEBUGCONSOLE
(For Mac OS X, ignore this and use the Xcode project)
SimpleDebugConsole requires CoreFoundation, which is a library that provides
similar semantics to the basic OpenStep Foundation classes and property list
handling, but in pure C. To get the latest version:
* Go to http://www.opensource.apple.com/darwinsource/
* Log in or sign up
* Click the "Source (x86)" link by the latest version of Mac OS X in the list
* Find the CF project (called CF-368.28 for Mac OS X 10.4.9, for instance)
* Click the .tar.gz link to download.
Supposedly CoreFoundation can be built under Windows and should be portable
to Linux with some fiddling. I can offer no real help on building it at this
time, however.
In addition, certain source files are shared with Oolite, and can be found at
../../src/Core/Debug/. These are:
* OOTCPStreamDecoder.h
* OOTCPStreamDecoder.c
* OODebugTCPConsoleProtocol.h
* OOTCPStreamDecoderAbstractionLayer.h
OOTCPStreamDecoderAbstractionLayer.m should *not* be used for the console.
Additionally, the macro OOTCPSTREAM_USE_COREFOUNDATION must be set to 1 (for
gcc, use -DOOTCPSTREAM_USE_COREFOUNDATION=1).
USING SIMPLEDEBUGCONSOLE
Drop the OXP Basic-debug.oxp into your AddOns directory. Run the console
(it should print the message "Waiting for connection"). Then run Oolite.
By default, the console listens on TCP port 8563. To use a different port,
pass it as an argument to the console and modify consple-port in a copy of
debugConfig.plist.
NOTE ON BASIC-DEBUG.OXP
This OXP is automatically generated by the Mac build process to ensure it
stays up to date, so don't check in any modifications to it. If you feel any
part of it needs to be altered, test the changes on a copy, then update the
corresponding files in ../../Mac-DebugOXP/Resources/.)
UNDERSTANDING SIMPLEDEBUGCONSOLE
The most important parts of the code are the two reusable components
OOTCPStreamDecoder (shared with Oolite) and OOConsoleConnection.
OOTCPStreamDecoder is used to extract property list "packets" from a stream of
data (presumed to be from a TCP connection, although it doesn't have to be)
encoded in the framing format used for the debug console protocol.
OOTCPStreamDecoder can be built to use either CoreFoundation or OpenStep
Foundation classes.
OOConsoleConnection is a higher-level component which wraps OOTCPStreamDecoder
and handles interpretation of property list packets. It implements the entire
debug console protocol, and communicates with client code using callbacks.
However, it does not deal with network connections directly; it requires
client code to provide the data. Although simpleDebugConsole only allows one
connection, OOConsoleConnection is designed to allow any number of connections
to exist in parallel.
main.c implements a simple single-connection TCP server which wraps an
OOConsoleConnection.
JAPrint.c implements printf and fprintf-like function which allow an addtional
format code, %@, which takes a CoreFoundation object.
JAAutoreleasePool.c implements OpenStep-like autorelease semantics for
CoreFoundation, simplifying memory management somewhat. A JAAutoreleasePool
must always exist when calling OOConsoleConnection or OOTCPStreamDecoder
functions, and should be destroyed afterwards to clean up memory used by those
functions.
For documentation on the debug console protocol, see
http://wiki.alioth.net/index.php/Oolite_debug_console_TCP_protocol .
|
