Ignore:
Timestamp:
11/24/08 00:32:12 (4 years ago)
Author:
KennethLavrsen
Message:

Item221: Updating TWiki:Codev to Foswiki:xxxxx
This requires a lot of work also on the Foswiki site so I get
something to point at. Had to recreate and refactor 4 or 5
developers docs in Development web.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/TWikiShellContrib/data/TWiki/UsingBuildContribAndTWikiShell.txt

    r878 r897  
    55 
    66 
    7 [[Foswiki:Extensions.BuildContrib][BuildContrib]] and [[Foswiki:Extensions.TWikiShellContrib][TWikiShellContrib]] are two very useful [[TWiki:Codev.TWikiExtensions][TWikiExtensions]] that can simplify the life of TWiki developers (both Core and Plugins) by automating the boring stuff (copying file around, running tests, packaging and uploading). 
    8  
    9 For the sake of simplicity, in this guide the term [[TWiki:Codev.TWikiExtensions][TWikiExtensions]] refers collectively (as defined by the community) to [[Foswiki:Extensions.PluginPackage][Plugins]], [[Foswiki:Extensions.AddOnPackage][Add-Ons]], [[Foswiki:Extensions.ContribPackage][Code Contributions]] and [[Foswiki:Extensions.SkinPackage][Skins]] 
     7[[Foswiki:Extensions.BuildContrib][BuildContrib]] and [[Foswiki:Extensions.TWikiShellContrib][TWikiShellContrib]] are two very useful extensions that can simplify the life of Foswiki developers (both Core and Plugins) by automating the boring stuff (copying file around, running tests, packaging and uploading). 
     8 
     9For the sake of simplicity, in this guide the term extension refers collectively (as defined by the community) to [[Foswiki:Extensions.PluginPackage][Plugins]], [[Foswiki:Extensions.AddOnPackage][Add-Ons]], [[Foswiki:Extensions.ContribPackage][Code Contributions]] and [[Foswiki:Extensions.SkinPackage][Skins]] 
    1010 
    1111---++ Overview 
    … …  
    3131For a complete documentation, check [[Foswiki:Extensions.TWikiShellContrib][Here]]. 
    3232 
    33 ---++ [[Foswiki:Extensions.BuildContrib][BuildContrib]] Quick guide to develop [[TWiki:Codev.TWikiExtensions][TWikiExtensions]] 
     33---++ [[Foswiki:Extensions.BuildContrib][BuildContrib]] Quick guide to develop [[Foswiki:Development.ExtensionDeveloperGuide][ExtensionDeveloperGuide]] 
    3434 
    3535On the surface, [[Foswiki:Extensions.BuildContrib][BuildContrib]] can be somehow intimidating, but it's concept is pretty simple: By having three files (=MANIFEST=, =DEPENDENCIES= and build.pl) in a known place under the directory, most of the development lifecycle tasks can be automated. 
    … …  
    3939[[Foswiki:Extensions.BuildContrib][BuildContrib]] makes some basic assumptions about the enviroment: 
    4040 
    41    * The [[TWiki:Codev.TWikiExtensions][TWikiExtensions]] is not being developed your plugin in a live TWiki installation (which is usually a really bad idea), but are instead doing the sensible thing and developing in a separate directory tree, usually - but not always - a CVS checkout area.  
    42    * The [[TWiki:Codev.TWikiExtensions][TWikiExtensions]] has a directory for itself outside the twiki root (ok, this is not an assumption, but if you try to generate a manifest for the [[TWiki:Codev.TWikiExtensions][TWikiExtensions]] from a twiki installation it'll end up with a lot of useless entries. Also, it's a good habit to acquire ;)) 
    43    * The enviroment variable TWIKI_LIBS has a colon-separated path list that may point anywhere needed to satisfied any of the [[TWiki:Codev.TWikiExtensions][TWikiExtension]] external dependencies. 
    44    * The enviroment variable TWIKI_HOME point to the root of your test TWiki installation. 
     41   * The extension is not being developed in a live Foswiki installation (which is usually a really bad idea), but are instead doing the sensible thing and developing in a separate directory tree, usually - but not always - a CVS checkout area.  
     42   * The extension has a directory for itself outside the twiki root (ok, this is not an assumption, but if you try to generate a manifest for the extensions from a Foswiki installation it'll end up with a lot of useless entries. Also, it's a good habit to acquire ;)) 
     43   * The enviroment variable TWIKI_LIBS has a colon-separated path list that may point anywhere needed to satisfied any of the extension external dependencies. 
     44   * The enviroment variable TWIKI_HOME point to the root of your test Foswiki installation. 
    4545   * The your module follows the standards for plugins and contribs i.e. that it 
    46       1. Has a topic in the data/TWiki directory  
    47       1. Has a perl module in the lib/TWiki/Plugins or lib/TWiki/Contrib directory 
     46      1. Has a topic in the data/System directory  
     47      1. Has a perl module in the lib/Foswiki/Plugins or lib/Foswiki/Contrib directory 
    4848      1. Has a sub-directory alongside the perl module that contains the extra .pm files specific to the module  
    4949 
    … …  
    5353 
    5454---++++ Create the Directory Structure 
    55 The first step to create a [[TWiki:Codev.TWikiExtensions][TWikiExtension]] is create the new directory structure in the checkout area, to maintain the repository up-to-date with local changes.   
    56  
    57 The recommended directory layout & content for [[TWiki:Codev.TWikiExtensions][TWikiExtension]] development is: 
     55The first step to create a extension is create the new directory structure in the checkout area, to maintain the repository up-to-date with local changes.   
     56 
     57The recommended directory layout & content for extension development is: 
    5858<verbatim> 
    5959|- twikiroot 
    6060|  |- twikiplugins 
    61 |  |  |- TWikiExtensionName 
     61|  |  |- FoswikiExtensionName 
    6262|  |  |  |- bin 
    6363|  |  |  |- lib 
    64 |  |  |  |  |- TWiki 
     64|  |  |  |  |- Foswiki 
    6565|  |  |  |  |  |- (Contrib|Plugins) 
    66 |  |  |  |  |  |  |- TWikiExtensionName 
     66|  |  |  |  |  |  |- FoswikiExtensionName 
    6767|  |  |  |  |  |  |  |- build.pl 
    6868|  |  |  |  |  |  |  |- MANIFEST 
    6969|  |  |  |  |  |  |  |- DEPENDENCIES  
    70 |  |  |  |  |  |  |- TWikiExtensionName.pm 
     70|  |  |  |  |  |  |- FoswikiExtensionName.pm 
    7171|  |  |  |- data 
    72 |  |  |  |  |- TWiki 
    73 |  |  |  |  |   |- TWikiExtensionName.txt 
     72|  |  |  |  |- System 
     73|  |  |  |  |   |- FoswikiExtensionName.txt 
    7474|  |  |  |- pub 
    7575|  |  |  |- tests 
    7676|  |  |  |  |- unit 
    77 |  |  |  |  |  |- TWikiExtensionNameSuite.pm 
     77|  |  |  |  |  |- FoswikiExtensionNameSuite.pm 
    7878|  |  |  |- templates 
    7979</verbatim> 
    … …  
    9090The =MANIFEST= file should read (at least): 
    9191<verbatim> 
    92 lib/TWiki/(Contrib|Plugins)/TWikiExtensionName.pm 
    93 data/TWiki/TWikiExtensionName.txt 
    94 tests/unit/TWikiExtensionNameSuite.pm 
     92lib/Foswiki/(Contrib|Plugins)/FoswikiExtensionName.pm 
     93data/System/FoswikiExtensionName.txt 
     94tests/unit/FoswikiExtensionNameSuite.pm 
    9595</verbatim> 
    9696 
    … …  
    9999For a complete description of the format of the =MANIFEST= and =DEPENDENCIES= files, check [[BuildContrib][Here]]. 
    100100 
    101 ---++++ "Installing" the TWikiExtension 
    102  
    103 To test the [[TWiki:Codev.TWikiExtensions][TWikiExtension]], it must be "installed" into the twikiroot. There are two options to do it: 
    104  
    105    1. Make the change in the plugins checkout area, and deploy them to the test TWiki installation OR 
    106    1. Deploy the plugin to the test TWiki installation, make the changes "live", and then copy back the modifications to the checkout area 
     101---++++ "Installing" the Foswiki Extension 
     102 
     103To test the extension, it must be "installed" into the foswikiroot. There are two options to do it: 
     104 
     105   1. Make the change in the plugins checkout area, and deploy them to the test Foswiki installation OR 
     106   1. Deploy the plugin to the test Foswiki installation, make the changes "live", and then copy back the modifications to the checkout area 
    107107 
    108108[[Foswiki:Extensions.BuildContrib][BuildContrib]] can help in the first case. Invoking 
    … …  
    132132=perl build.pl release= 
    133133 
    134 and it will create a =.zip= and a  =.tar.gz= files based in the content of the =MANIFEST= file and an installer called =TWikiExtensionName_installer= (ie. =SamplePlugin_installer=). All these files will be created in the "root" of the plugin directory. (ie: under =twikiplugins/SamplePlugin=). 
    135 As part of the release process, the [[TWiki:Codev.TWikiExtensions][TWikiExtension]] topic is processed an the following tags will be replaced: 
    136    * =%$MANIFEST%= - TWiki table of files in =MANIFEST=  
     134and it will create a =.zip= and a  =.tar.gz= files based in the content of the =MANIFEST= file and an installer called =FoswikiExtensionName_installer= (ie. =SamplePlugin_installer=). All these files will be created in the "root" of the plugin directory. (ie: under =twikiplugins/SamplePlugin=). 
     135As part of the release process, the extension topic is processed an the following tags will be replaced: 
     136   * =%$MANIFEST%= - Foswiki table of files in =MANIFEST=  
    137137   * =%$DEPENDENCIES%= - list of dependencies from =DEPENDENCIES=  
    138138   * =%$VERSION%= version from $VERSION in main .pm  
    … …  
    141141 
    142142 
    143 ---++++ Uploading the changes to TWiki.org 
    144 As the last step of the development lifecycle, the released version must be uploaded to the proper topic in TWiki.org. 
     143---++++ Uploading the changes to foswiki.org 
     144As the last step of the development lifecycle, the released version must be uploaded to the proper topic in foswiki.org. 
    145145To do this, invoke: 
    146146 
    147147=perl build.pl upload= 
    148148 
    149 and [[Foswiki:Extensions.BuildContrib][BuildContrib]] will create the release package, and upload it automatically to the proper place in TWiki.org. 
    150  
    151 ---++ [[Foswiki:Extensions.TWikiShellContrib][TWikiShellContrib]] Quick guide to develop [[TWiki:Codev.TWikiExtensions][TWikiExtensions]] 
     149and [[Foswiki:Extensions.BuildContrib][BuildContrib]] will create the release package, and upload it automatically to the proper place in foswiki.org. 
     150 
     151---++ [[Foswiki:Extensions.TWikiShellContrib][TWikiShellContrib]] Quick guide to develop extensions. 
    152152 
    153153The default [[Foswiki:Extensions.CommandSet][CommandSets]] bundled with [[Foswiki:Extensions.TWikiShellContrib][TWikiShellContrib]] can be used to simplify even more the development process, by complementing the operatios already performed by [[Foswiki:Extensions.BuildContrib][BuildContrib]]. 
    … …  
    167167 
    168168---++++ Create the Directory Structure 
    169 The first step to create a [[TWiki:Codev.TWikiExtensions][TWikiExtension]] is create the new directory structure in the checkout area, to maintain the repository up-to-date with local changes.  
     169The first step to create an extension is to create the new directory structure in the checkout area, to maintain the repository up-to-date with local changes.  
    170170 
    171171The directory structure is as follows: 
    172172 
    173 A typical directory layout & content for [[TWiki:Codev.TWikiExtensions][TWikiExtension]] development is: 
     173A typical directory layout & content for extension development is: 
    174174<verbatim> 
    175175|- twikiroot 
    176176|  |- twikiplugins 
    177 |  |  |- TWikiExtensionName 
     177|  |  |- FoswikiExtensionName 
    178178|  |  |  |- MANIFEST 
    179179|  |  |  |- DEPENDENCIES  
    180180|  |  |  |- bin 
    181181|  |  |  |- lib 
    182 |  |  |  |  |- TWiki 
     182|  |  |  |  |- Foswiki 
    183183|  |  |  |  |  |- (Contrib|Plugins) 
    184 |  |  |  |  |  |  |- TWikiExtensionName 
     184|  |  |  |  |  |  |- FoswikiExtensionName 
    185185|  |  |  |  |  |  |  |- build.pl 
    186 |  |  |  |  |  |  |- TWikiExtensionName.pm 
     186|  |  |  |  |  |  |- FoswikiExtensionName.pm 
    187187|  |  |  |- data 
    188 |  |  |  |  |- TWiki 
    189 |  |  |  |  |   |- TWikiExtensionName.txt 
     188|  |  |  |  |- System 
     189|  |  |  |  |   |- FoswikiExtensionName.txt 
    190190|  |  |  |- pub 
    191191|  |  |  |- tests 
    192192|  |  |  |  |- unit 
    193 |  |  |  |  |  |- TWikiExtensionNameSuite.pm 
     193|  |  |  |  |  |- FoswikiExtensionNameSuite.pm 
    194194|  |  |  |- templates 
    195195</verbatim> 
    … …  
    199199To create this structure, invoke: 
    200200 
    201 =perl twikishell plugin create !TWikiExtensionName= 
     201=perl twikishell plugin create !FoswikiExtensionName= 
    202202 
    203203and [[Foswiki:Extensions.TWikiShellContrib][TWikiShellContrib]] will create the directory structure with empty skeletons for all the files. The =MANIFEST= file is created automatically. 
    … …  
    205205The =MANIFEST= file should read: 
    206206<verbatim> 
    207 lib/TWiki/Plugins/TWikiExtensionName.pm 
    208 data/TWiki/TWikiExtensionName.txt 
    209 tests/unit/TWikiExtensionNameSuite.pm 
     207lib/Foswiki/Plugins/FoswikiExtensionName.pm 
     208data/System/FoswikiExtensionName.txt 
     209tests/unit/FoswikiExtensionNameSuite.pm 
    210210</verbatim> 
    211211 
    212212Note that none of the special files used by [[Foswiki:Extensions.BuildContrib][BuildContrib]] is in the =MANIFEST=, because they are usually not distributed to end-users. 
    213213 
    214 ---++++ "Installing" the [[TWiki:Codev.TWikiExtensions][TWikiExtension]] 
    215  
    216 [[Foswiki:Extensions.TWikiShellContrib][TWikiShellContrib]] follows the second option: Deploy the plugin to the test TWiki installation, make the changes "live", and then copy back the modifications to the checkout area. 
     214---++++ "Installing" the extension 
     215 
     216[[Foswiki:Extensions.TWikiShellContrib][TWikiShellContrib]] follows the second option: Deploy the plugin to the test Foswiki installation, make the changes "live", and then copy back the modifications to the checkout area. 
    217217 
    218218For that, invoke: 
    219219 
    220 =perl twikishell plugin develop !TWikiExtension= 
    221  
    222 and it will copy all the content of the plugin directory intro the twiki installation. Also, two files called =TWikiExtensionName.MF= and =TWikiExtensionName.DEP= are created in the twiki root. =TWikiExtension.MF= will have a list of all the copied files, and should be identical to the =MANIFEST= file. Similary, the =TWikiExtension.DEP= should be identical to the =DEPENDENCIES= file. 
     220=perl twikishell plugin develop !FoswikiExtension= 
     221 
     222and it will copy all the content of the plugin directory intro the twiki installation. Also, two files called =FoswikiExtensionName.MF= and =FoswikiExtensionName.DEP= are created in the twiki root. =FoswikiExtension.MF= will have a list of all the copied files, and should be identical to the =MANIFEST= file. Similary, the =FoswikiExtension.DEP= should be identical to the =DEPENDENCIES= file. 
    223223 
    224224Now, all the changes can be made "live". 
    … …  
    226226After all the changes, invoke: 
    227227 
    228 =perl twikishell plugin putback !TWikiExtension= 
    229  
    230 and it will copy all the files listed in =TWikiExtension.MF= back to the checkout area, updating the =MANIFEST= and =DEPENDENCIES= with the content of =TWikiExtension.MF= and =TWikiExtension.DEP= respectively. 
     228=perl twikishell plugin putback !FoswikiExtension= 
     229 
     230and it will copy all the files listed in =FoswikiExtension.MF= back to the checkout area, updating the =MANIFEST= and =DEPENDENCIES= with the content of =FoswikiExtension.MF= and =FoswikiExtension.DEP= respectively. 
    231231 
    232232---++++ Adding or Removing files 
    233233 
    234 When adding or removing files from the package, the =TWikiExtension.MF= must be updated so the proper =MANIFEST= file can be generated later. 
     234When adding or removing files from the package, the =FoswikiExtension.MF= must be updated so the proper =MANIFEST= file can be generated later. 
    235235 
    236236---++++ Running tests 
    … …  
    238238If =Test::Unit= is installed in the system, invoking 
    239239 
    240 =perl twikishell runtest !TWikiExtensionSuite= 
    241  
    242 will try to run automatically the =tests/unit/TWikiExtensionSuite.pm= module. 
     240=perl twikishell runtest !FoswikiExtensionSuite= 
     241 
     242will try to run automatically the =tests/unit/FoswikiExtensionSuite.pm= module. 
    243243 
    244244---++++ Preparing the release package 
    … …  
    248248So, to create the release file, invoke 
    249249 
    250 =perl twikishell build !TWikiExtension release= 
     250=perl twikishell build !FoswikiExtension release= 
    251251 
    252252and it will call automatically the proper =build.pl= script with the =release= target 
    253253 
    254 ---++++ Uploading the changes to TWiki.org 
     254---++++ Uploading the changes to foswiki.org 
    255255 
    256256In the same way as releasing the package, invoking 
    257257 
    258 =perl twikishell build !TWikiExtension upload= 
     258=perl twikishell build !FoswikiExtension upload= 
    259259 
    260260will call automatically the proper =build.pl= script with the =upload= target. 
    … …  
    262262---++++ Additional Operation: Packaging the development version 
    263263 
    264 If for some reason there is the need to package the whole development version of a !TWikiExtension (including the =MANIFEST=, =DEPENDENCIES=,etc), invoke: 
    265  
    266 =perl twikishell package !TWikiExtension= 
     264If for some reason there is the need to package the whole development version of an Extension (including the =MANIFEST=, =DEPENDENCIES=,etc), invoke: 
     265 
     266=perl twikishell package !FoswikiExtension= 
    267267 
    268268and it'll create a =tar.gz= file with all the files in the plugin directory 
    … …  
    270270---++ Summary 
    271271 
    272 Combining [[Foswiki:Extensions.TWikiShellContrib][TWikiShellContrib]] and [[Foswiki:Extensions.BuildContrib][BuildContrib]] ease the development of [[TWiki:Codev.TWikiExtensions][TWikiExtensions]]. The lifecycle becomes: 
    273  
    274    * =perl twikishell plugin create !TWikiExtension= 
    275    * =perl twikishell plugin develop !TWikiExtension= 
    276    * =perl twikishell runtest !TWikiExtension= or  =perl twikishell build !TWikiExtension test= 
    277    * =perl twikishell plugin putback !TWikiExtension= 
    278    * (optionally) =perl twikishell build release !TWikiExtension= 
    279    * (optionally) =perl twikishell package !TWikiExtension= 
    280    * =perl twikishell build upload !TWikiExtension= 
     272Combining [[Foswiki:Extensions.TWikiShellContrib][TWikiShellContrib]] and [[Foswiki:Extensions.BuildContrib][BuildContrib]] ease the development of extensions. The lifecycle becomes: 
     273 
     274   * =perl twikishell plugin create !FoswikiExtension= 
     275   * =perl twikishell plugin develop !FoswikiExtension= 
     276   * =perl twikishell runtest !FoswikiExtension= or  =perl twikishell build !FoswikiExtension test= 
     277   * =perl twikishell plugin putback !FoswikiExtension= 
     278   * (optionally) =perl twikishell build release !FoswikiExtension= 
     279   * (optionally) =perl twikishell package !FoswikiExtension= 
     280   * =perl twikishell build upload !FoswikiExtension= 
    281281 
    282282This could be quite verbose, but creating the proper shellscripts (invoking =perl twikishell shorcuts=), they are abbreviated to: 
    283283 
    284    * =plugin create !TWikiExtension= 
    285    * =plugin develop !TWikiExtension= 
    286    * =runtest !TWikiExtension= or  =build !TWikiExtension test= 
    287    * =plugin putback !TWikiExtension= 
    288    * (optionally) =build release !TWikiExtension= 
    289    * (optionally) =package !TWikiExtension= 
    290    * =build upload !TWikiExtension= 
     284   * =plugin create !FoswikiExtension= 
     285   * =plugin develop !FoswikiExtension= 
     286   * =runtest !FoswikiExtension= or  =build !FoswikiExtension test= 
     287   * =plugin putback !FoswikiExtension= 
     288   * (optionally) =build release !FoswikiExtension= 
     289   * (optionally) =package !FoswikiExtension= 
     290   * =build upload !FoswikiExtension= 
Note: See TracChangeset for help on using the changeset viewer.