[38075] branches/gsoc08-framework/MacPorts.Framework
armahg at macports.org
armahg at macports.org
Sat Jul 5 12:53:53 PDT 2008
Revision: 38075
http://trac.macosforge.org/projects/macports/changeset/38075
Author: armahg at macports.org
Date: 2008-07-05 12:53:53 -0700 (Sat, 05 Jul 2008)
Log Message:
-----------
Added more Documentation to Framework classes
Modified Paths:
--------------
branches/gsoc08-framework/MacPorts.Framework/MPInterpreter.h
branches/gsoc08-framework/MacPorts.Framework/MPMacPorts.h
branches/gsoc08-framework/MacPorts.Framework/MPMacPorts.m
branches/gsoc08-framework/MacPorts.Framework/MPPort.h
branches/gsoc08-framework/MacPorts.Framework/MPReceipt.h
Modified: branches/gsoc08-framework/MacPorts.Framework/MPInterpreter.h
===================================================================
--- branches/gsoc08-framework/MacPorts.Framework/MPInterpreter.h 2008-07-05 19:48:47 UTC (rev 38074)
+++ branches/gsoc08-framework/MacPorts.Framework/MPInterpreter.h 2008-07-05 19:53:53 UTC (rev 38075)
@@ -50,7 +50,7 @@
@abstract Tcl interpreter object
@discussion Contains a shared per-thread instance of a Tcl interpreter. The MPInterpreter class
is where the Objective-C API meets the Tcl command line. It is a per-thread interpreter to allow
- for users of the API to multi-thread their programs without relative ease.
+ users of the API to multi-thread their programs with relative ease.
*/
@interface MPInterpreter : NSObject {
@@ -73,15 +73,36 @@
/*!
@brief Returns the NSstring result of evaluating a Tcl expression
@param statement An NSArray containing the Tcl expression
+ @discussion For example, here is the header definition of a MacPorts Tcl API
+ call proc macports::getindex {source}. This is how to call this procedure
+ in Tcl: [macports::getindex $source]. Calling the macports::getindex
+ procedure from Objective-C code with -evaluateArrayAsString however takes the following form:
+
+ [SomeMPInterpreterObject evaluateArrayAsString:[NSArray arrayWithObjects:
+ @"return [macports::getindex",
+ [NSString stringWithString:@"SomeValidMacPortsSourcePath"],
+ @"]",
+ nil]];
+
+ Each element in the array is an NSString. Note the "return" in the first element of the statement
+ NSArray.
*/
- (NSString *)evaluateArrayAsString:(NSArray *)statement;
/*!
@brief Returns the NSString result of evaluating a Tcl expression
@param statement An NSString containing the Tcl expression
+ @discussion Using the macports::getindex {source} procedure as an example (see discussion for
+ -evaluateArrayAsString), we have the following Objective-C form for calling the macports::getindex
+ procedure:
+
+ [SomeMPInterpreterObject evaluateStringAsString:
+ [NSString stringWithString:@"return [macports::getindex SomeValidMacPortsSourcePath]"]];
*/
- (NSString *)evaluateStringAsString:(NSString *)statement;
+
+
/*!
@brief Returns an NSArray whose elements are the the elements of a Tcl list in the form of an NSString
@param list A Tcl list in the form of an NSString
Modified: branches/gsoc08-framework/MacPorts.Framework/MPMacPorts.h
===================================================================
--- branches/gsoc08-framework/MacPorts.Framework/MPMacPorts.h 2008-07-05 19:48:47 UTC (rev 38074)
+++ branches/gsoc08-framework/MacPorts.Framework/MPMacPorts.h 2008-07-05 19:53:53 UTC (rev 38075)
@@ -35,7 +35,7 @@
/*!
@header
- MPMacPorts represents an installation of the MacPorts on a user's system. A user can have
+ MPMacPorts represents an installation of MacPorts on a user's system. A user can have
multiple MacPorts installations in different locations.
*/
@@ -77,27 +77,24 @@
/*!
- @brief Returns an NSDictionary of ports
+ @brief Returns an NSDictionary of ports. Calls [self search:query caseSensiitve:YES].
@param query An NSString containing name or partial name of port being searched.
@discussion The keys are NSString names of the ports whilst the values are the respective MPPort objects
- (Double check this)
*/
- (NSDictionary *)search:(NSString *)query;
/*!
- @brief Returns an NSDictionary of ports
+ @brief Returns an NSDictionary of ports. Calls [self search:query caseSensitive:sensitivity matchStyle:@"regex"].
@param query An NSString containing name (full or parital) of port being searched.
@param sensitivity A Boolean value indicating whether or not the search should be case sensitive
@discussion The keys are NSString names of the ports whilst the values are the respective MPPort objects
- (Double check this)
*/
- (NSDictionary *)search:(NSString *)query caseSensitive:(BOOL)sensitivity;
/*!
- @brief Returns an NSDictionary of ports
+ @brief Returns an NSDictionary of ports. Calls [self search:query caseSensitive:sensitivity matchStyle:style field:@"name"].
@param query An NSString containing name (full or parital) of port being searched.
@param sensitivity A Boolean value indicating whether or not the search should be case sensitive
@param style TALK TO RANDALL ABOUT WHAT THIS IS
@discussion The keys are NSString names of the ports whilst the values are the respective MPPort objects
- (Double check this)
*/
- (NSDictionary *)search:(NSString *)query caseSensitive:(BOOL)sensitivity matchStyle:(NSString *)style;
/*!
@@ -107,13 +104,12 @@
@param style TALK TO RANDALL ABOUT WHAT THIS IS
@param fieldName TALK TO RANDALL ABOUT WHAT THIS IS
@discussion The keys are NSString names of the ports whilst the values are the respective MPPort objects
- (Double check this)
*/
- (NSDictionary *)search:(NSString *)query caseSensitive:(BOOL)sensitivity matchStyle:(NSString *)style field:(NSString *)fieldName;
/*!
- @brief Returns an NSArray of MPPorts that a port depends on
+ @brief Returns an NSArray of NSString port names that a port depends on
@param port The MPPort whose dependecies is being sought
*/
- (NSArray *)depends:(MPPort *)port;
@@ -124,35 +120,11 @@
@param target The NSString representing a given target
@Discussion The various options for target are: configure, build,
test, destroot, install, archive, dmg, mdmg, pkg, mpkg, rpm, dpkg, srpm.
- (Should include more notes and what each of these do). Users of -exec
- are responsible for ensuring that execution happens in an authorized environment for
- various targets.
+ Users of -exec are responsible for ensuring that execution happens in
+ an authorized environment for various targets.
*/
- (void)exec:(MPPort *)port withTarget:(NSString *)target;
-/*Convenience methods based on the exec: withTarget: method
- I DON'T KNOW IF SOME OF OF THESE METHODS REQUIRE EXTRA ARGUMENTS
- CHECK THAT WITH RANDALL
- */
--(void)configure:(MPPort *)port;
--(void)build:(MPPort *)port;
--(void)test:(MPPort *)port;
--(void)destroot:(MPPort *)port;
--(void)install:(MPPort *)port;
--(void)archive:(MPPort *)port;
--(void)createDmg:(MPPort *)port;
--(void)createMdmg:(MPPort *)port;
--(void)createPkg:(MPPort *)port;
--(void)createMpkg:(MPPort *)port;
--(void)createRpm:(MPPort *)port;
--(void)createDpkg:(MPPort *)port;
--(void)createSrpm:(MPPort *)port;
-
-
-
-
-
-
/*!
@brief Returns the NSString path to the directory where ports are installed.
*/
@@ -175,7 +147,8 @@
/*!
@brief Returns the NSURL of the portIndex file on this MacPorts system for a given ports tree
@param source An NSString containing the file path to the ports tree
- @Discussion The PortIndex contains a list of descriptions ports and is where they are searched for
+ @Discussion The PortIndex is a list of serialized Tcl key-value lists, one list
+ per line. This is where ports are searched for.
*/
- (NSURL *)pathToPortIndex:(NSString *)source;
Modified: branches/gsoc08-framework/MacPorts.Framework/MPMacPorts.m
===================================================================
--- branches/gsoc08-framework/MacPorts.Framework/MPMacPorts.m 2008-07-05 19:48:47 UTC (rev 38074)
+++ branches/gsoc08-framework/MacPorts.Framework/MPMacPorts.m 2008-07-05 19:53:53 UTC (rev 38075)
@@ -137,48 +137,7 @@
- (void)exec:(MPPort *)port withTarget:(NSString *)target {
return [port exec:target];
}
--(void)configure:(MPPort *)port {
- [port configure];
-}
--(void)build:(MPPort *)port {
- [port build];
-}
--(void)test:(MPPort *)port {
- [port test];
-}
--(void)destroot:(MPPort *)port {
- [port destroot];
-}
--(void)install:(MPPort *)port {
- [port install];
-}
--(void)archive:(MPPort *)port {
- [port archive];
-}
--(void)createDmg:(MPPort *)port {
- [port createDmg];
-}
--(void)createMdmg:(MPPort *)port {
- [port createMdmg];
-}
--(void)createPkg:(MPPort *)port {
- [port createPkg];
-}
--(void)createMpkg:(MPPort *)port {
- [port createMpkg];
-}
--(void)createRpm:(MPPort *)port {
- [port createRpm];
-}
--(void)createDpkg:(MPPort *)port {
- [port createDpkg];
-}
--(void)createSrpm:(MPPort *)port {
- [port createSrpm];
-}
-
-
#pragma settings
- (NSString *)prefix {
Modified: branches/gsoc08-framework/MacPorts.Framework/MPPort.h
===================================================================
--- branches/gsoc08-framework/MacPorts.Framework/MPPort.h 2008-07-05 19:48:47 UTC (rev 38074)
+++ branches/gsoc08-framework/MacPorts.Framework/MPPort.h 2008-07-05 19:53:53 UTC (rev 38075)
@@ -104,6 +104,11 @@
DEPENDENCY EACH DEPENDENCY IS?
*/
- (NSArray *)depends;
+
+
+
+
+#pragma mark --exec: and its convenience methods--
/*!
@brief Executes the specified target for this MPPort
@param target NSString target to be executed for this MPPort
@@ -112,59 +117,71 @@
- (void)exec:(NSString *)target;
/*Convenience methods based on the exec: withTarget: method
- I DON'T KNOW IF SOME OF OF THESE METHODS REQUIRE EXTRA ARGUMENTS
- CHECK THAT WITH RANDALL
+ These methods and -exec: need to be rewritten to handle variants
+ and options.
+ Also, there is currently a bug with packaging targets (See
+ http://trac.macports.org/ticket/10881 for more information).
+ Should we run exec:@"destroot" before any of the packaging commands?"
*/
+
/*!
- @brief
+ @brief Runs a configure process for this port.
*/
-(void)configure;
/*!
- @brief
+ @brief Builds this port.
*/
-(void)build;
/*!
- @brief
+ @brief Tests this port.
*/
-(void)test;
/*!
- @brief
+ @brief Installs this port to a temporary directory
*/
-(void)destroot;
/*!
- @brief
+ @brief Installs this port.
*/
-(void)install;
/*!
- @brief
+ @brief Archives port for later unarchving.
+ @discussion Archive mode must be enabled for this command to work.
+ This is done by setting portarchivemode to yes in the macports.conf file
+ located in ${prefix}/etc/macports/macports.conf. With archive mode enabled,
+ binary archives are created automatically whenever an install is performed.
*/
-(void)archive;
/*!
- @brief
+ @brief Creates an internet-enabled disk image containing OS X package of this
+ port
*/
-(void)createDmg;
/*!
- @brief
+ @brief Create an internet-enabled disk image containing an OS X metapackage of this
+ port
*/
-(void)createMdmg;
/*!
- @brief
+ @brief Creates an OS X installer package of this port
*/
-(void)createPkg;
/*!
- @brief
+ @brief Creates an OS X installer metapackage of this this port and
+ its dependencies
*/
-(void)createMpkg;
/*!
- @brief
+ @brief Creates and RPM binary package of this port. This is similar to a
+ tgz "archive".
*/
-(void)createRpm;
/*!
- @brief
+ @brief Creates a DEB binary package of this port.
*/
-(void)createDpkg;
/*!
- @brief
+ @brief Creates an SRPM source package of this port, similar to a xar "portpkg".
*/
-(void)createSrpm;
@@ -194,11 +211,8 @@
/*!
@brief Sets the state of this MPPort object from its receipts
@param receipts An NSArray of receipts for this port
- @discussion
-
- AGAIN NEED TO ASK RANDALL ABOUT THIS METHOD. I THINK A PORT CAN HAVE MORE THAN ONE RECEIPT
- THAT REPRESENT ITS VARIOUS VERSIONS / VARIANTS THAT HAVE BEEN INSTALLED SINCE EACH
- INSTALLATION HAS ITS OWN RECEIPT.
+ @discussion It is possible for an installed port to have more than one
+ receipt if the MacPorts system uses hardlinks to activate the port.
*/
- (void)setStateFromReceipts:(NSArray *)receipts;
Modified: branches/gsoc08-framework/MacPorts.Framework/MPReceipt.h
===================================================================
--- branches/gsoc08-framework/MacPorts.Framework/MPReceipt.h 2008-07-05 19:48:47 UTC (rev 38074)
+++ branches/gsoc08-framework/MacPorts.Framework/MPReceipt.h 2008-07-05 19:53:53 UTC (rev 38075)
@@ -53,7 +53,7 @@
/*!
@brief This method initializes the MPReceipt object with a name, version, revision, variants, active state and long description.
@param array An NSArray object containing the values for initializing this MPReceipt.
- @discussion DOUBLE CHECK THIS WITH RANDALL
+ @discussion
The MPReceipt object contains an internal dictionary whose keys are the following strings: name, version, revision, variants,
active, whatIsThis. The values for these keys are provided by the initializing array parameter.
*/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/macports-changes/attachments/20080705/137b26d6/attachment.html
More information about the macports-changes
mailing list