diff options
Diffstat (limited to 'pear/docs')
| -rw-r--r-- | pear/docs/Archive_Tar.txt | 424 | ||||
| -rw-r--r-- | pear/docs/rfc01_PEAR_pecl-binaries.txt | 88 | ||||
| -rw-r--r-- | pear/docs/rfc01_PEAR_subpackages.txt | 65 |
3 files changed, 0 insertions, 577 deletions
diff --git a/pear/docs/Archive_Tar.txt b/pear/docs/Archive_Tar.txt deleted file mode 100644 index 73bee0d786..0000000000 --- a/pear/docs/Archive_Tar.txt +++ /dev/null @@ -1,424 +0,0 @@ -Documentation for class Archive_Tar -=================================== -Last update : 2001-08-15 - - - -Overview : ----------- - - The Archive_Tar class helps in creating and managing GNU TAR format - files compressed by GNU ZIP or not. - The class offers basic functions like creating an archive, adding - files in the archive, extracting files from the archive and listing - the archive content. - It also provide advanced functions that allow the adding and - extraction of files with path manipulation. - - -Sample : --------- - - // ----- Creating the object (uncompressed archive) - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->setErrorHandling(PEAR_ERROR_PRINT); - - // ----- Creating the archive - $v_list[0]="file.txt"; - $v_list[1]="data/"; - $v_list[2]="file.log"; - $tar_object->create($v_list); - - // ----- Adding files - $v_list[0]="dev/file.txt"; - $v_list[1]="dev/data/"; - $v_list[2]="log/file.log"; - $tar_object->add($v_list); - - // ----- Adding more files - $tar_object->add("release/newfile.log release/readme.txt"); - - // ----- Listing the content - if (($v_list = $tar_object->listContent()) != 0) - for ($i=0; $i<sizeof($v_list); $i++) - { - echo "Filename :'".$v_list[$i][filename]."'<br>"; - echo " .size :'".$v_list[$i][size]."'<br>"; - echo " .mtime :'".$v_list[$i][mtime]."' (".date("l dS of F Y h:i:s A", $v_list[$i][mtime]).")<br>"; - echo " .mode :'".$v_list[$i][mode]."'<br>"; - echo " .uid :'".$v_list[$i][uid]."'<br>"; - echo " .gid :'".$v_list[$i][gid]."'<br>"; - echo " .typeflag :'".$v_list[$i][typeflag]."'<br>"; - } - - // ----- Extracting the archive in directory "install" - $tar_object->extract("install"); - - -Public arguments : ------------------- - -None - - -Public Methods : ----------------- - -Method : Archive_Tar($p_tarname, $compress = false) -Description : - Archive_Tar Class constructor. This flavour of the constructor only - declare a new Archive_Tar object, identifying it by the name of the - tar file. - If the compress argument is set the tar will be read or created as a - gzip compressed TAR file. -Arguments : - $p_tarname : A valid filename for the tar archive file. - $p_compress : true/false. Indicate if the archive need to be - compressed or not. -Return value : - The Archive_Tar object. -Sample : - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object_compressed = new Archive_Tar("tarname.tgz", true); -How it works : - Initialize the object. - -Method : create($p_filelist) -Description : - This method creates the archive file and add the files / directories - that are listed in $p_filelist. - If the file already exists and is writable, it is replaced by the - new tar. It is a create and not an add. If the file exists and is - read-only or is a directory it is not replaced. The method return - false and a PEAR error text. - The $p_filelist parameter can be an array of string, each string - representing a filename or a directory name with their path if - needed. It can also be a single string with names separated by a - single blank. - See also createModify() method for more details. -Arguments : - $p_filelist : An array of filenames and directory names, or a single - string with names separated by a single blank space. -Return value : - true on success, false on error. -Sample 1 : - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->setErrorHandling(PEAR_ERROR_PRINT); // Optional error handling - $v_list[0]="file.txt"; - $v_list[1]="data/"; (Optional '/' at the end) - $v_list[2]="file.log"; - $tar_object->create($v_list); -Sample 2 : - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->setErrorHandling(PEAR_ERROR_PRINT); // Optional error handling - $tar_object->create("file.txt data/ file.log"); -How it works : - Just calling the createModify() method with the right parameters. - -Method : createModify($p_filelist, $p_add_dir, $p_remove_dir = "") -Description : - This method creates the archive file and add the files / directories - that are listed in $p_filelist. - If the file already exists and is writable, it is replaced by the - new tar. It is a create and not an add. If the file exists and is - read-only or is a directory it is not replaced. The method return - false and a PEAR error text. - The $p_filelist parameter can be an array of string, each string - representing a filename or a directory name with their path if - needed. It can also be a single string with names separated by a - single blank. - The path indicated in $p_remove_dir will be removed from the - memorized path of each file / directory listed when this path - exists. By default nothing is removed (empty path "") - The path indicated in $p_add_dir will be added at the beginning of - the memorized path of each file / directory listed. However it can - be set to empty "". The adding of a path is done after the removing - of path. - The path add/remove ability enables the user to prepare an archive - for extraction in a different path than the origin files are. - See also addModify() method for file adding properties. -Arguments : - $p_filelist : An array of filenames and directory names, or a single - string with names separated by a single blank space. - $p_add_dir : A string which contains a path to be added to the - memorized path of each element in the list. - $p_remove_dir : A string which contains a path to be removed from - the memorized path of each element in the list, when - relevant. -Return value : - true on success, false on error. -Sample 1 : - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->setErrorHandling(PEAR_ERROR_PRINT); // Optional error handling - $v_list[0]="file.txt"; - $v_list[1]="data/"; (Optional '/' at the end) - $v_list[2]="file.log"; - $tar_object->createModify($v_list, "install"); - // files are stored in the archive as : - // install/file.txt - // install/data - // install/data/file1.txt - // install/data/... all the files and sub-dirs of data/ - // install/file.log -Sample 2 : - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->setErrorHandling(PEAR_ERROR_PRINT); // Optional error handling - $v_list[0]="dev/file.txt"; - $v_list[1]="dev/data/"; (Optional '/' at the end) - $v_list[2]="log/file.log"; - $tar_object->createModify($v_list, "install", "dev"); - // files are stored in the archive as : - // install/file.txt - // install/data - // install/data/file1.txt - // install/data/... all the files and sub-dirs of data/ - // install/log/file.log -How it works : - Open the file in write mode (erasing the existing one if one), - call the _addList() method for adding the files in an empty archive, - add the tar footer (512 bytes block), close the tar file. - - -Method : addModify($p_filelist, $p_add_dir, $p_remove_dir="") -Description : - This method add the files / directories listed in $p_filelist at the - end of the existing archive. If the archive does not yet exists it - is created. - The $p_filelist parameter can be an array of string, each string - representing a filename or a directory name with their path if - needed. It can also be a single string with names separated by a - single blank. - The path indicated in $p_remove_dir will be removed from the - memorized path of each file / directory listed when this path - exists. By default nothing is removed (empty path "") - The path indicated in $p_add_dir will be added at the beginning of - the memorized path of each file / directory listed. However it can - be set to empty "". The adding of a path is done after the removing - of path. - The path add/remove ability enables the user to prepare an archive - for extraction in a different path than the origin files are. - If a file/dir is already in the archive it will only be added at the - end of the archive. There is no update of the existing archived - file/dir. However while extracting the archive, the last file will - replace the first one. This results in a none optimization of the - archive size. - If a file/dir does not exist the file/dir is ignored. However an - error text is send to PEAR error. - If a file/dir is not readable the file/dir is ignored. However an - error text is send to PEAR error. - If the resulting filename/dirname (after the add/remove option or - not) string is greater than 99 char, the file/dir is - ignored. However an error text is send to PEAR error. -Arguments : - $p_filelist : An array of filenames and directory names, or a single - string with names separated by a single blank space. - $p_add_dir : A string which contains a path to be added to the - memorized path of each element in the list. - $p_remove_dir : A string which contains a path to be removed from - the memorized path of each element in the list, when - relevant. -Return value : - true on success, false on error. -Sample 1 : - $tar_object = new Archive_Tar("tarname.tar"); - [...] - $v_list[0]="dev/file.txt"; - $v_list[1]="dev/data/"; (Optional '/' at the end) - $v_list[2]="log/file.log"; - $tar_object->addModify($v_list, "install"); - // files are stored in the archive as : - // install/file.txt - // install/data - // install/data/file1.txt - // install/data/... all the files and sub-dirs of data/ - // install/file.log -Sample 2 : - $tar_object = new Archive_Tar("tarname.tar"); - [...] - $v_list[0]="dev/file.txt"; - $v_list[1]="dev/data/"; (Optional '/' at the end) - $v_list[2]="log/file.log"; - $tar_object->addModify($v_list, "install", "dev"); - // files are stored in the archive as : - // install/file.txt - // install/data - // install/data/file1.txt - // install/data/... all the files and sub-dirs of data/ - // install/log/file.log -How it works : - If the archive does not exists it create it and add the files. - If the archive does exists and is not compressed, it open it, jump - before the last empty 512 bytes block (tar footer) and add the files - at this point. - If the archive does exists and is compressed, a temporary copy file - is created. This temporary file is then 'gzip' read block by block - until the last empty block. The new files are then added in the - compressed file. - The adding of files is done by going through the file/dir list, - adding files per files, in a recursive way through the - directory. Each time a path need to be added/removed it is done - before writing the file header in the archive. - -Method : add($p_filelist) -Description : - This method add the files / directories listed in $p_filelist at the - end of the existing archive. If the archive does not yet exists it - is created. - The $p_filelist parameter can be an array of string, each string - representing a filename or a directory name with their path if - needed. It can also be a single string with names separated by a - single blank. - See addModify() method for details and limitations. -Arguments : - $p_filelist : An array of filenames and directory names, or a single - string with names separated by a single blank space. -Return value : - true on success, false on error. -Sample 1 : - $tar_object = new Archive_Tar("tarname.tar"); - [...] - $v_list[0]="dev/file.txt"; - $v_list[1]="dev/data/"; (Optional '/' at the end) - $v_list[2]="log/file.log"; - $tar_object->add($v_list); -Sample 2 : - $tar_object = new Archive_Tar("tarname.tgz", true); - [...] - $v_list[0]="dev/file.txt"; - $v_list[1]="dev/data/"; (Optional '/' at the end) - $v_list[2]="log/file.log"; - $tar_object->add($v_list); -How it works : - Simply call the addModify() method with the right parameters. - -Method : extract($p_path = "") -Description : - This method extract all the content of the archive in the directory - indicated by $p_path.If $p_path is optional, if not set the archive - is extracted in the current directory. - While extracting a file, if the directory path does not exists it is - created. - See extractModify() for details and limitations. -Arguments : - $p_path : Optional path where the files/dir need to by extracted. -Return value : - true on success, false on error. -Sample : - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->extract(); -How it works : - Simply call the extractModify() method with appropriate parameters. - -Method : extractModify($p_path, $p_remove_path) -Description : - This method extract all the content of the archive in the directory - indicated by $p_path. When relevant the memorized path of the - files/dir can be modified by removing the $p_remove_path path at the - beginning of the file/dir path. - While extracting a file, if the directory path does not exists it is - created. - While extracting a file, if the file already exists it is replaced - without looking for last modification date. - While extracting a file, if the file already exists and is write - protected, the extraction is aborted. - While extracting a file, if a directory with the same name already - exists, the extraction is aborted. - While extracting a directory, if a file with the same name already - exists, the extraction is aborted. - While extracting a file/directory if the destination directory exist - and is write protected, or does not exist but can not be created, - the extraction is aborted. - If after extraction an extracted file does not show the correct - stored file size, the extraction is aborted. - When the extraction is aborted, a PEAR error text is set and false - is returned. However the result can be a partial extraction that may - need to be manually cleaned. -Arguments : - $p_path : The path of the directory where the files/dir need to by - extracted. - $p_remove_path : Part of the memorized path that can be removed if - present at the beginning of the file/dir path. -Return value : - true on success, false on error. -Sample : - // Imagine tarname.tar with files : - // dev/data/file.txt - // dev/data/log.txt - // readme.txt - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->extractModify("install", "dev"); - // Files will be extracted there : - // install/data/file.txt - // install/data/log.txt - // install/readme.txt -How it works : - Open the archive and call a more generic function that can extract - only a part of the archive or all the archive. - See extractList() method for more details. - -Method : listContent() -Description : - This method returns an array of arrays that describe each - file/directory present in the archive. - The array is not sorted, so it show the position of the file in the - archive. - The file informations are : - $file[filename] : Name and path of the file/dir. - $file[mode] : File permissions (result of fileperms()) - $file[uid] : user id - $file[gid] : group id - $file[size] : filesize - $file[mtime] : Last modification time (result of filemtime()) - $file[typeflag] : "" for file, "5" for directory -Arguments : -Return value : - An array of arrays or 0 on error. -Sample : - $tar_object = new Archive_Tar("tarname.tar"); - if (($v_list = $tar_object->listContent()) != 0) - for ($i=0; $i<sizeof($v_list); $i++) - { - echo "Filename :'".$v_list[$i][filename]."'<br>"; - echo " .size :'".$v_list[$i][size]."'<br>"; - echo " .mtime :'".$v_list[$i][mtime]."' (". - date("l dS of F Y h:i:s A", $v_list[$i][mtime]).")<br>"; - echo " .mode :'".$v_list[$i][mode]."'<br>"; - echo " .uid :'".$v_list[$i][uid]."'<br>"; - echo " .gid :'".$v_list[$i][gid]."'<br>"; - echo " .typeflag :'".$v_list[$i][typeflag]."'<br>"; - } -How it works : - Call the same function as an extract however with a flag to only go - through the archive without extracting the files. - -Method : extractList($p_filelist, $p_path = "", $p_remove_path = "") -Description : - This method extract from the archive only the files indicated in the - $p_filelist. These files are extracted in the current directory or - in the directory indicated by the optional $p_path parameter. - If indicated the $p_remove_path can be used in the same way as it is - used in extractModify() method. -Arguments : - $p_filelist : An array of filenames and directory names, or a single - string with names separated by a single blank space. - $p_path : The path of the directory where the files/dir need to by - extracted. - $p_remove_path : Part of the memorized path that can be removed if - present at the beginning of the file/dir path. -Return value : - true on success, false on error. -Sample : - // Imagine tarname.tar with files : - // dev/data/file.txt - // dev/data/log.txt - // readme.txt - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->extractList("dev/data/file.txt readme.txt", "install", - "dev"); - // Files will be extracted there : - // install/data/file.txt - // install/readme.txt -How it works : - Go through the archive and extract only the files present in the - list. - diff --git a/pear/docs/rfc01_PEAR_pecl-binaries.txt b/pear/docs/rfc01_PEAR_pecl-binaries.txt deleted file mode 100644 index 767a486503..0000000000 --- a/pear/docs/rfc01_PEAR_pecl-binaries.txt +++ /dev/null @@ -1,88 +0,0 @@ -Author: Tomas V.V.Cox <cox@idecnet.com> -Revision: $Id$ -Abstract: Open discussion on how to handle PECL binary packages - - -pecl package name ------------------ - -The name of the extension would be: - -peclfoo-bin-<OS>-<ARCH>-3.1.2.tgz - -The os (Operating system) and arch (CPU type), would be the value -returned by the OS_Guess class. - -package creation ----------------- - -pear package [-t <type>] <package> - --t <type> The type of package you want to generate (pear, rpm, -msi, src, etc) - -Without args it will package the extension as it does nowadays (the -same as "-t src"). - -We have now native pear packages, rpm, msi is planned and others -will surely come. Additionally of generating the native package description -file, we could perhaps also call the tools for generating the whole package. - -An idea would be to create in addition a BUILDINFO.txt file with some data about -the env where the extension was compiled at, like the -php version, the php_uname(), the extra libs versions, os vendor -version, pear version, etc. - -package.xml ------------ - -As a binary release shares the same release data with the source -distrib, the same package.xml file could be used for all kind of -distribs. Let's say something like: - -<release> - <version>... - <date> - <notes> - <filelist>.. - <file role="ext" platform=""> - </filelist> -</release> - -A package may contain many compiled extensions for different platforms, -one single extension or the sources. - - -Installation ------------- - -pear install -t bin peclfoo (download and install the binary distrib of -peclfoo for your current OS-ARCH) - -pear install peclfoo (download, build and install peclfoo) - -All the files with role="ext" would be installed -in "ext_dir" (pear cmd setting). The user can config it with "pear config-set ext_dir=XXX". -If this var is not explicitly set, the following will be used for -finding a default location: - -if (getenv('PHP_PEAR_EXTENSION_DIR')) { - define('PEAR_CONFIG_DEFAULT_EXT_DIR', getenv('PHP_PEAR_EXTENSION_DIR')); - } else { - if (ini_get('extension_dir')) { - define('PEAR_CONFIG_DEFAULT_EXT_DIR', ini_get('extension_dir')); - } elseif (defined('PEAR_EXTENSION_DIR') && @is_dir(PEAR_EXTENSION_DIR)) { - define('PEAR_CONFIG_DEFAULT_EXT_DIR', PEAR_EXTENSION_DIR); - } elseif (defined('PHP_EXTENSION_DIR')) { - define('PEAR_CONFIG_DEFAULT_EXT_DIR', PHP_EXTENSION_DIR); - } else { - define('PEAR_CONFIG_DEFAULT_EXT_DIR', '.'); - } -} - -Listing in the web ------------------- - -A new column "Type" should be added to the release listing under the -package home page at pear.php.net, saying that the package is a binary -distrib compiled for OS X and ARCH Y or sources. diff --git a/pear/docs/rfc01_PEAR_subpackages.txt b/pear/docs/rfc01_PEAR_subpackages.txt deleted file mode 100644 index af068892e0..0000000000 --- a/pear/docs/rfc01_PEAR_subpackages.txt +++ /dev/null @@ -1,65 +0,0 @@ -RFC: subpackages -Sept. 17, 2003 -Greg Beaver - -The Problem: ------------- -Many PEAR packages consist of a core and several ancillary self-contained program elements. Examples are: - -MDB/DB and database drivers -Log and log classes -Cache and Cache drivers -phpDocumentor and Converters -HTML_QuickForm and HTML_QuickForm_Controller - -In most cases, not all packages need be installed. The most common example of this is DB: how many people need to use every single database driver? Most of them just eat up disk space, except on multi-user installations. - -In addition, each ancillary program element may have a different stability level (sqlite driver may be beta quality, while the mysql driver is stable). Currently, this results in a contradiction: the core is stable, but one driver is not. What is the stability of the package? stable or beta? People who want to only install and use stable packages may be deceived by a package that is marked stable and contains an alpha-quality driver, for example. - -Plus, many PEAR packages are criticized for their bloat. - -The Solution: -------------- -Subpackages will allow the solving of all of these problems. Note that subpackaging does not address other problems, such as bundling together related packages (PFC packages, for example, or packages needed for a framework that need not have any dependencies). Subpackages are a dependency relation. In other words, if Package Foo depends on Bar, Foo is not necessarily a subpackage of Bar, but might be. However, if Foo does not depend on Bar, Foo is definitively NOT a subpackage of Bar. - -In other words, subpackages by definition cannot function without the presence of the core package (DB drivers are pretty pointless without DB). - -Note that with the presence of subpackages, a subpackages can be released with a new version number without need to release a new version of the core, allowing rapid development on unstable subpackages, and slower development on stable components. - -How to differentiate a subpackage from a normal dependency: ------------------------------------------------------------ -An addition should be made to the package.dtd file for package.xml files. A new dependency type, "spkg" should be used to define a subpackage dependency. This dependency type should be used by subpackages to definitively link to a parent package as a subpackage. - -example package Foo_Bar's package.xml dependency: - -<dep type="spkg" rel="has">Foo</dep> <!-- this subpackage works with all Foo --> --or- -<dep type="spkg" rel="ge" version="1.5">Foo</dep> <!-- works with v1.5 or newer --> - -All rel values would be available including "not" if a particular version of the parent package must not be installed due to a bug affecting this particular subpackage (rare case). - -package Foo's package.xml dependencies may contain an optional dependency on the subpackage: - -<dep type="pkg" rel="has" optional="yes">Foo_Bar</dep> - -standard subpackages must be listed as optional dependencies in package.xml to allow easy installation with the --alldeps switch, but third party subpackages need not be listed as optional dependencies (if someone releases a custom DB driver or specialized phpDocumentor converter, for example, on their own website) - -Note that a required subpackage must be bundled as part of the core, and is not a subpackage - a subpackage MUST be an optional dependency. - -Naming/Path Conventions: ------------------------- -Subpackages must reside in a subdirectory of the parent package, just as they would under normal circumstances as part of the package. Foo's subpackage Bar must be named Foo_Bar, and reside in Foo/Bar.php as per PEAR conventions. - -pear.php.net changes: ---------------------- -Subpackages would not be listed globally, but instead on the package page as optional components. - -Documentation for subpackages will reside as part of the main package's documentation. - -PEAR Installer changes: ------------------------ -pear info/remote-info would list available subpackages (remote-info only) and installed subpackages (info only) - -pear list would list top-level packages, with some indication of packages that have subpackages (an asterisk or something). pear list PackageWithSubpackages would list subpackages as well - -pear uninstall PackageWithSubpackages would automatically uninstall any subpackages without requiring --force or other switches, as if they were simply a part of the main application. This is due to the fact that they would be simply a part of the package if PEAR didn't support subpackages. |