User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
en:devel:packagemodules [2014/04/21 01:42]
joebordes
en:devel:packagemodules [2016/01/26 14:50] (current)
Line 1: Line 1:
 ====== How to prepare modules for distribution ====== ====== How to prepare modules for distribution ======
  
-coreBOS is prepared to make installing and distributing your modules easy.+ 
 +<WRAP center round alert 60%> 
 +**THIS DOCUMENTATION IS WRONG**. It is obsolete. We're working on it 
 +</​WRAP>​ 
 + 
 + 
 +coreBOS ​(5.5 forward) ​is prepared to make installing and distributing your modules easy.
  
 There are basically two approaches for this: There are basically two approaches for this:
-  - distribute your module as an individual package that can be installed on any system once it is up and running +  - distribute your module as an individual package that can be installed on any system once it is up and running. 
-  - distribute your module as part of the whole system and have it appear as an optional ​module ​for your users to select or as a mandatory ​module ​that will be installed+  - distribute your module as part of the whole system and have the administrator activate the module as needed. 
 + 
 +The first step is to create the new module in an existing system, so install ​coreBOS system on your development machine and let's get started. 
 + 
 +===== Create new module ​or extension =====
  
-The first step of obtaining the package file must be done to be able to distribute it on installation.+[[en:​devel:​createvtlibmodule|You can find full details on how to create a coreBOS module or extension here.]]
  
 ===== Create module package ===== ===== Create module package =====
Line 17: Line 27:
 ==== 1.- File structure ==== ==== 1.- File structure ====
 You must have these files in place: You must have these files in place:
-  * build/​{ModuleName}/​manifest.xml 
   * modules/​{ModuleName}   * modules/​{ModuleName}
 +  * modules/​{ModuleName}/​manifest.xml
 +  * manifest.xml (this is a copy of the modules/​{ModuleName}/​manifest.xml file)
 +  * composer.json (optional, this is for direct command line install [[https://​getcomposer.org/​|using composer]])
   * cron/​modules/​{ModuleName} ​ (**optional** only if needed)   * cron/​modules/​{ModuleName} ​ (**optional** only if needed)
   * Smarty/​templates/​modules/​{ModuleName} ​ (**optional** only if needed)   * Smarty/​templates/​modules/​{ModuleName} ​ (**optional** only if needed)
 +
 +The complete composer.json format supported is:
 +
 +<code json>
 +{
 +    "​name":​ "​Package",​
 +    "​type":​ "​object",​
 +    "​properties":​ {
 +        "​name":​ {
 +            "​type":​ "​string",​
 +            "​description":​ "​Package name, including '​vendor-name/'​ prefix."​
 +        },
 +        "​description":​ {
 +            "​type":​ "​string",​
 +            "​description":​ "Short package description."​
 +        },
 +        "​keywords":​ {
 +            "​type":​ "​array",​
 +            "​items":​ {
 +                "​type":​ "​string",​
 +                "​description":​ "A tag/keyword that this package relates to."
 +            }
 +        },
 +        "​homepage":​ {
 +            "​type":​ "​string",​
 +            "​description":​ "​Homepage URL for the project.",​
 +            "​format":​ "​uri"​
 +        },
 +        "​version":​ {
 +            "​type":​ "​string",​
 +            "​description":​ "​Package version, see https://​getcomposer.org/​doc/​04-schema.md#​version for more info on valid schemes."​
 +        },
 +        "​time":​ {
 +            "​type":​ "​string",​
 +            "​description":​ "​Package release date, in '​YYYY-MM-DD',​ '​YYYY-MM-DD HH:​MM:​SS'​ or '​YYYY-MM-DDTHH:​MM:​SSZ'​ format."​
 +        },
 +        "​license":​ {
 +            "​type":​ ["​string",​ "​array"​],​
 +            "​description":​ "​License name. Or an array of license names."​
 +        },
 +        "​extra":​ {
 +            "​price":​ [number],
 +            "​buyemail":​ [email],
 +            "​buyurl":​ [uri],
 +            "​distribution":​ ["​Sale","​Free","​Subscription","​Donationware"​]
 +        },
 +        "​authors":​ {
 +            "​type":​ "​array",​
 +            "​description":​ "List of authors that contributed to the package. This is typically the main maintainers,​ not the full list.",​
 +            "​items":​ {
 +                "​type":​ "​object",​
 +                "​additionalProperties":​ false,
 +                "​required":​ [ "​name"​],​
 +                "​properties":​ {
 +                    "​name":​ {
 +                        "​type":​ "​string",​
 +                        "​description":​ "Full name of the author."​
 +                    },
 +                    "​email":​ {
 +                        "​type":​ "​string",​
 +                        "​description":​ "Email address of the author.",​
 +                        "​format":​ "​email"​
 +                    },
 +                    "​homepage":​ {
 +                        "​type":​ "​string",​
 +                        "​description":​ "​Homepage URL for the author.",​
 +                        "​format":​ "​uri"​
 +                    },
 +                    "​role":​ {
 +                        "​type":​ "​string",​
 +                        "​description":​ "​Author'​s role in the project."​
 +                    }
 +                }
 +            }
 +        },
 +        "​support":​ {
 +            "​type":​ "​object",​
 +            "​properties":​ {
 +                "​email":​ {
 +                    "​type":​ "​string",​
 +                    "​description":​ "Email address for support.",​
 +                    "​format":​ "​email"​
 +                },
 +                "​issues":​ {
 +                    "​type":​ "​string",​
 +                    "​description":​ "URL to the issue tracker.",​
 +                    "​format":​ "​uri"​
 +                },
 +                "​forum":​ {
 +                    "​type":​ "​string",​
 +                    "​description":​ "URL to the forum.",​
 +                    "​format":​ "​uri"​
 +                },
 +                "​wiki":​ {
 +                    "​type":​ "​string",​
 +                    "​description":​ "URL to the wiki.",​
 +                    "​format":​ "​uri"​
 +                },
 +                "​irc":​ {
 +                    "​type":​ "​string",​
 +                    "​description":​ "IRC channel for support, as irc://​server/​channel.",​
 +                    "​format":​ "​uri"​
 +                },
 +                "​source":​ {
 +                    "​type":​ "​string",​
 +                    "​description":​ "URL to browse or download the sources.",​
 +                    "​format":​ "​uri"​
 +                },
 +                "​docs":​ {
 +                    "​type":​ "​string",​
 +                    "​description":​ "URL to the documentation.",​
 +                    "​format":​ "​uri"​
 +                }
 +            }
 +        }
 +    }
 +}
 +</​code>​
 +
 +where only the first **//​name//​** and **//​type//​** are mandatory.
  
 ==== 2.- Package the module ==== ==== 2.- Package the module ====
-There are different ways to acheive ​this.+There are different ways to achieve ​this.
  
 ==== Linux shell access ==== ==== Linux shell access ====
Line 102: Line 234:
   *To install the module in an already installed application load the package file through the **Module Manager** interface.   *To install the module in an already installed application load the package file through the **Module Manager** interface.
  
 +===== Creating a Bundle Package =====
 +
 +A bundle package is a file which contains 2 or more normal packages to be installed together in a certain order.
 +
 +In order to construct these packages what we usually do is take all the steps above for each individual package and then manually create the manifest file and zip them all together.
 +
 +In the build directory you can see how we have set this up for the Project bundle. Since we use links we can call the pack.sh script to get the bundle packaged.
 +
 +
 +===== Comments and Tips =====
  
 +  * Note how, by default we have all the modules packaged in the packages directory, but also ALL files copied in place. This way we can work on any module and simply create the package again when we are finished with the modifications.
 +  * In line with the previous comment, we setup in the build directory the structure to work on the manifest file and link all the structure to the real files which are in their place.
 +  * The previous situation leads to the all to common error of modifying files to fix or add something and forgetting to create the package again. To avoid this problem the install process will automatically create the package again right before it installs as long as all the necessary files are in place. This means that all files in the application are more important than files inside the package.
 +  * Another common situation is where you already have an installed application and want to apply a set of modules and changes. In this case it is normal to create a central script that directs all the changes and at one point it installs the set of new modules. When this is done it is **very recommendable** to first create the package files again before installing to avoid the situation described before.