From 5366bd558e33339b4b3878d30f7b7351d330725d Mon Sep 17 00:00:00 2001 From: Adam Fedor Date: Mon, 26 Jan 2004 04:42:28 +0000 Subject: [PATCH] Doc updates git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@18485 72102866-910b-0410-8b05-ffd578937521 --- ChangeLog | 10 + Documentation/GNUmakefile | 2 +- Documentation/General/Debugging.gsdoc | 184 ++++++++++++++++++ Documentation/General/GNUmakefile | 67 +++++++ .../{ => General}/OpenStepCompliance.gsdoc | 0 Source/DocMakefile | 6 - base.make.in | 4 +- 7 files changed, 264 insertions(+), 9 deletions(-) create mode 100644 Documentation/General/Debugging.gsdoc create mode 100644 Documentation/General/GNUmakefile rename Documentation/{ => General}/OpenStepCompliance.gsdoc (100%) diff --git a/ChangeLog b/ChangeLog index 4c6432075..4e52e4e4c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2004-01-25 Adam Fedor + + * base.make.in: Move LIBXML variable outside gnu-foundation check. + + * Documentation/GNUmakefile (SUBPROJECTS): Add General + * Documentation/General/GNUmakefile: New file. + * Documentation/General/Degbugging.gsdoc: Moved to here. + * Documentation/General/OpenStepCompliance.gsdoc: Idem. + * Source/DocMakefile: Remove OpenStepCompliance.gsdoc + 2004-01-25 Richard Frith-Macdonald * Source/NSPropertyList.m: Fix bug in encoding integers as xml. diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile index 9372cce3d..9f827d0a1 100644 --- a/Documentation/GNUmakefile +++ b/Documentation/GNUmakefile @@ -32,7 +32,7 @@ include ../config.mak # The documents to be generated DOCUMENT_NAME = coding-standards -SUBPROJECTS = manual +SUBPROJECTS = manual General # The text documents to be generated DOCUMENT_TEXT_NAME = \ diff --git a/Documentation/General/Debugging.gsdoc b/Documentation/General/Debugging.gsdoc new file mode 100644 index 000000000..7742ee7db --- /dev/null +++ b/Documentation/General/Debugging.gsdoc @@ -0,0 +1,184 @@ + + + + + Debugging with GDB + + + + + Debugging +

+ 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. +

+
+ Basic GDB usage +

+ To start the debugger, specify the program you want to debug: +

+ + gdb myprogram + +

+ With GNUstep you can also use the debugtool and debugapp scripts + to begin a debugging session: +

+ + debugapp MyApp.app + +

+ Following is a short list of important commands that gdb accepts. + After this list, a more detailed explaination of each command is + given. +

+ + run args - Run the program + break func/method - Stop at a function or method + print var/func - Print value of a variable/function + backtrace - List the fuction stack + frame value - Move up and down the fuction stack + help - Get help on gdb commands + quit - Quit the program + +
+ +
+ The run command +

+ 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: +

+ + run -NSOpen=afile.txt + +
+ +
+ The break command +

+ 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. +

+ + break afile.m:345 + +

+ will stop the debugger at line 345 in the file afile.m. +

+ + break a_function + +

+ will tell the debugger to stop at the beggining of the + a_function 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 +

+ + -[Class methodName] + +

+ 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 Class and method name methodName are + enclosed in brackets, similar to the way messages are specified + in Objective-C source code. For example, to set a breakpoint at + the create instance method of class Fruit + in the program currently being debugged, enter: +

+ + break -[Fruit create] + +

+ One can also specify just a method name: +

+ + break initWithValue: + +

+ 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. +

+
+ +
+ The print command +

+ The print command can be used to display a wide variety of information + that gdb knows about the program. As with the break 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. +

+ + print aVariable + print anIvar + print self->anIvar + print anArray[4] + print aStruct.subvalue + print *(int *)pointerValue + +

+ 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: +

+ + print aVariable = 4 + +

+ One can also print the value of a function. Here gdb will actually + call the function you specify and return the output: +

+ + print my_function(4, "hithere") + +

+ When debugging Objective-C programs, the same thing can be done + with methods. +

+ + print -[object hash] + +

+ A special command has been added to gdb to print the + description of an object (based on the method of the + same name). This is the print-object (or po) + command: +

+ + po anObject + +

+ Which is the same as typing +

+ + print -[myObject desciption] + +
+ +
+ Other command +

+ The clear, info line, jump, + and list commands also accept Objective-C method + syntax for specifying locations. +

+
+ + + + + diff --git a/Documentation/General/GNUmakefile b/Documentation/General/GNUmakefile new file mode 100644 index 000000000..0e755f6fc --- /dev/null +++ b/Documentation/General/GNUmakefile @@ -0,0 +1,67 @@ +# +# Makefile for GNUstep Base Library documentation. +# +# Copyright (C) 2002 Free Software Foundation, Inc. +# +# Written by: Richard Frith-Macdonald +# +# 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 + diff --git a/Documentation/OpenStepCompliance.gsdoc b/Documentation/General/OpenStepCompliance.gsdoc similarity index 100% rename from Documentation/OpenStepCompliance.gsdoc rename to Documentation/General/OpenStepCompliance.gsdoc diff --git a/Source/DocMakefile b/Source/DocMakefile index 18fc75eff..94a0f15b0 100644 --- a/Source/DocMakefile +++ b/Source/DocMakefile @@ -33,7 +33,6 @@ BaseAdditions_DOC_INSTALL_DIR = Developer Base_AGSDOC_FILES = \ ../Documentation/Base.gsdoc \ -../Documentation/OpenStepCompliance.gsdoc \ NSArchiver.h \ NSArray.h \ NSAttributedString.h \ @@ -172,7 +171,6 @@ include $(GNUSTEP_MAKEFILES)/documentation.make # before-all:: ../Documentation/Base \ ../Documentation/Base/Functions.gsdoc \ - ../Documentation/Base/OpenStepCompliance.gsdoc \ ../Documentation/Base/TypesAndConstants.gsdoc \ ../Documentation/BaseAdditions \ ../Documentation/BaseAdditions/Functions.gsdoc \ @@ -186,10 +184,6 @@ before-all:: ../Documentation/Base \ ../Documentation/Base/Functions.gsdoc: ../Documentation/Functions.gsdoc cp ../Documentation/Functions.gsdoc ../Documentation/Base -../Documentation/Base/OpenStepCompliance.gsdoc: \ - ../Documentation/OpenStepCompliance.gsdoc - cp ../Documentation/OpenStepCompliance.gsdoc ../Documentation/Base - ../Documentation/Base/TypesAndConstants.gsdoc: \ ../Documentation/TypesAndConstants.gsdoc cp ../Documentation/TypesAndConstants.gsdoc ../Documentation/Base diff --git a/base.make.in b/base.make.in index fcc31f6b5..fc5036867 100644 --- a/base.make.in +++ b/base.make.in @@ -37,8 +37,6 @@ ifeq ($(FOUNDATION_LIB),gnu) GNUSTEP_BASE_MINOR_VERSION = @MINOR_VERSION@ GNUSTEP_BASE_SUBMINOR_VERSION = @SUBMINOR_VERSION@ - GNUSTEP_BASE_HAVE_LIBXML=@HAVE_LIBXML@ - FND_LDFLAGS = FND_LIBS = -lgnustep-base FND_DEFINE = -DGNUSTEP_BASE_LIBRARY=1 @@ -50,4 +48,6 @@ ifeq ($(FOUNDATION_LIB),gnu) endif endif + GNUSTEP_BASE_HAVE_LIBXML=@HAVE_LIBXML@ + endif # BASE_MAKE_LOADED