gnustep/libs-base
0
0
Fork 0
mirror of https://github.com/gnustep/libs-base.git synced 2025-05-29 16:01:38 +00:00
Code Issues Projects Releases Packages Wiki Activity

Doc updates

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@18485 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Adam Fedor 2004-01-26 04:42:28 +00:00
parent 6306bb3bf0
commit 5366bd558e
7 changed files with 264 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

184
Documentation/General/Debugging.gsdoc Normal file
View file

@ -0,0 +1,184 @@
<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.0//EN" "http://www.gnustep.org/gsdoc-1_0_0.xml">
<gsdoc base="Debugging" up="Tools">
<head>
<title>Debugging with GDB</title>
<author name="Adam Fedor"></author>
</head>
<body>
<chapter>
<heading>Debugging</heading>
<p>
GDB is the GNU debugger and is the main method used for debugging
Objective-C programs. Full support for debugging Objective-C with
GDB was added in version 6.0. This document will describe the
various features of GDB that help with debugging Objective-C programs.
However, GDB is a very complex program, and not everything that it
can do will be described here.
</p>
<section>
<heading>Basic GDB usage</heading>
<p>
To start the debugger, specify the program you want to debug:
</p>
<example>
gdb myprogram
</example>
<p>
With GNUstep you can also use the debugtool and debugapp scripts
to begin a debugging session:
</p>
<example>
debugapp MyApp.app
</example>
<p>
Following is a short list of important commands that gdb accepts.
After this list, a more detailed explaination of each command is
given.
</p>
<list>
<item>run <var>args</var> - Run the program</item>
<item>break <var>func/method</var> - Stop at a function or method</item>
<item>print <var>var/func</var> - Print value of a variable/function</item>
<item>backtrace - List the fuction stack</item>
<item>frame <var>value</var> - Move up and down the fuction stack</item>
<item>help - Get help on gdb commands</item>
<item>quit - Quit the program</item>
</list>
</section>
<section>
<heading>The <em>run</em> command</heading>
<p>
This command starts the program inside the debugger. You can optionally
add arguments to the run command and these arguments will get passed
directly to the program as normal command-line arguments. For instance,
you might want to start an application and open a file:
</p>
<example>
run -NSOpen=afile.txt
</example>
</section>
<section>
<heading>The <em>break</em> command</heading>
<p>
This command instructs the debugger to stop when it reaches a
certain location in the program. The syntax for break can be very
complex. However we will only cover some simple examples. One instance
is to break on a particular line number.
</p>
<example>
break afile.m:345
</example>
<p>
will stop the debugger at line 345 in the file <file>afile.m</file>.
</p>
<example>
break a_function
</example>
<p>
will tell the debugger to stop at the beggining of the
<code>a_function</code> function. Finally, and most importantly
for Objective-C programs, you can enter a fully-qualified or
partially-qualified method name to stop at.
A fully qualified Objective-C method name is specified as
</p>
<example>
-[Class methodName]
</example>
<p>
where the minus sign is used to indicate an instance method and
a plus sign (not shown) is used to indicate a class method. The
class name <var>Class</var> and method name <var>methodName</var> are
enclosed in brackets, similar to the way messages are specified
in Objective-C source code. For example, to set a breakpoint at
the <code>create</code> instance method of class <code>Fruit</code>
in the program currently being debugged, enter:
</p>
<example>
break -[Fruit create]
</example>
<p>
One can also specify just a method name:
</p>
<example>
break initWithValue:
</example>
<p>
gdb will automatically determine what class this method belongs to. If
there is more than one class that implements this method, you will
be presented with a list of classes that implement the method from which
you must chose one.
</p>
</section>
<section>
<heading>The <em>print</em> command</heading>
<p>
The print command can be used to display a wide variety of information
that gdb knows about the program. As with the <var>break</var> command,
the variety of things you can do is very large, but we will discuss only
a few of the things that can be done. Below are several simple examples
of printing the value of a variable.
</p>
<example>
print aVariable
print anIvar
print self->anIvar
print anArray[4]
print aStruct.subvalue
print *(int *)pointerValue
</example>
<p>
Note that you can specify variables in the same way you specify them
in source code, using array subscripts, pointer dereferences, etc.
You can also set the value of a variable using print:
</p>
<example>
print aVariable = 4
</example>
<p>
One can also print the value of a function. Here gdb will actually
call the function you specify and return the output:
</p>
<example>
print my_function(4, "hithere")
</example>
<p>
When debugging Objective-C programs, the same thing can be done
with methods.
</p>
<example>
print -[object hash]
</example>
<p>
A special command has been added to gdb to print the
<var>description</var> of an object (based on the method of the
same name). This is the <var>print-object</var> (or <var>po</var>)
command:
</p>
<example>
po anObject
</example>
<p>
Which is the same as typing
</p>
<example>
print -[myObject desciption]
</example>
</section>
<section>
<heading>Other command</heading>
<p>
The <var>clear</var>, <var>info line</var>, <var>jump</var>,
and <var>list</var> commands also accept Objective-C method
syntax for specifying locations.
</p>
</section>
</chapter>
</body>
</gsdoc>

67
Documentation/General/GNUmakefile Normal file
View file

@ -0,0 +1,67 @@
#
# Makefile for GNUstep Base Library documentation.
#
# Copyright (C) 2002 Free Software Foundation, Inc.
#
# Written by: Richard Frith-Macdonald <rfm.gnu.org>
#
# This file is part of the GNUstep Base Library.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Library General Public
# License as published by the Free Software Foundation; either
# version 2 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Library General Public License for more details.
#
# You should have received a copy of the GNU Library General Public
# License along with this library; if not, write to the Free
# Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA
#
# Install into the system root by default
GNUSTEP_INSTALLATION_DIR = $(GNUSTEP_SYSTEM_ROOT)
include $(GNUSTEP_MAKEFILES)/common.make
DOCUMENT_NAME = BaseGeneral
BaseGeneral_DOC_INSTALL_DIR = Developer
BaseGeneral_AGSDOC_FILES = \
Debugging.gsdoc \
OpenStepCompliance.gsdoc \
#
# Hack ... using the -DocumentationDirectory flag overrides the value
# used by the make package, and puts our output in the documentation
# directory.
#
#BaseGeneral_AGSDOC_FLAGS = -DocumentationDirectory .
# Use local version of autogsdoc in case it is not installed
AUTOGSDOC=../../Tools/obj/autogsdoc
include $(GNUSTEP_MAKEFILES)/documentation.make
#
# Ensure that our destination subdirectory exists in the Documentation
# directory, and temporarily copy the base source file here for autogsdoc
# to use.
#
#before-all::
#
# Clean up temporary files used while generating documentation.
#
after-clean::
if [ -d BaseGeneral ]; then \
$(RM) BaseGeneral/stamp; \
$(RM) BaseGeneral/dependencies; \
rmdir BaseGeneral; \
fi

93
Documentation/General/OpenStepCompliance.gsdoc Normal file
View file

@ -0,0 +1,93 @@
<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.0//EN" "http://www.gnustep.org/gsdoc-1_0_0.xml">
<gsdoc base="OpenStepCompliance" up="Base">
<head>
<title>OpenStep Compliance</title>
<author name="Adam Fedor"></author>
</head>
<body>
<chapter>
<heading>Classes</heading>
<p>
This file documents the complance of all the classes in the
GNUstep Base library. Note that the following is just a best guess
as to the compliance of the classes. Each class was checked to make
sure it implemented all the documented OpenStep methods and functions.
In addition, extensive testing has been performed on the GNUstep Base
Library, and it is believed, to the best of our knowledge, that it
operates according to the OpenStep specification, with the caveat that
there are always bugs in any implementation and there are most likely
bugs in the current implementation that we are not aware of.
</p>
<p>
The following classes conform to the OpenStep specification:
</p>
<list>
<item>NSArchiver</item>
<item>NSArray</item>
<item>NSAssertionHandler</item>
<item>NSAutoreleasePool</item>
<item>NSBundle</item>
<item>NSCalendarDate</item>
<item>NSCharacterSet</item>
<item>NSCoder</item>
<item>NSConditionLock</item>
<item>NSConnection</item>
<item>NSCountedSet</item>
<item>NSData</item>
<item>NSDate</item>
<item>NSDeserializer</item>
<item>NSDictionary</item>
<item>NSDistantObject</item>
<item>NSEnumerator</item>
<item>NSException</item>
<item>NSInvocation</item>
<item>NSLock</item>
<item>NSMethodSignature</item>
<item>NSMutableArray</item>
<item>NSMutableCharacterSet</item>
<item>NSMutableData</item>
<item>NSMutableDictionary</item>
<item>NSMutableSet</item>
<item>NSMutableString</item>
<item>NSNotification</item>
<item>NSNotificationCenter</item>
<item>NSNotificationQueue</item>
<item>NSNumber</item>
<item>NSObject</item>
<item>NSProcessInfo</item>
<item>NSProxy</item>
<item>NSRecursiveLock</item>
<item>NSRunLoop</item>
<item>NSScanner</item>
<item>NSSerializer</item>
<item>NSSet</item>
<item>NSString</item>
<item>NSThread</item>
<item>NSTimer</item>
<item>NSTimeZone</item>
<item>NSTimeZoneDetail</item>
<item>NSUnarchiver</item>
<item>NSUserDefaults</item>
<item>NSValue</item>
<item>All Protocols</item>
<item>All Functions</item>
</list>
<p>
The following OpenStep classes are not implemented. The usefulness
of these classes it marginal so it is likely that we will never
implement these classes. However, we would be pleased to accept
their contribution should anyone care to implement them and assign
the copyright to the Free Software Foundation.
</p>
<list>
<item>NSBTreeBlock</item>
<item>NSBTreeCursor</item>
<item>NSByteStore</item>
<item>NSByteStoreFile</item>
</list>
</chapter>
</body>
</gsdoc>