{"comment":{"created_at":"2011-10-17T16:02:17Z","body":"The utility \"qnt\" is currently under development in the XP framework's\nexperiments.\n\n\n\nfriebe, Mon, 12 May 2008 17:53:43 +0200","updated_at":"2011-10-17T16:02:17Z","url":"https://api.github.com/repos/xp-framework/rfc/issues/comments/2430824","id":2430824,"user":{"gravatar_id":"26f07e3b262e9a80436f368cb11bd0c2","avatar_url":"https://secure.gravatar.com/avatar/26f07e3b262e9a80436f368cb11bd0c2?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png","url":"https://api.github.com/users/thekid","id":696742,"login":"thekid"}},"action":"created","issue":{"number":166,"created_at":"2011-10-17T16:02:13Z","pull_request":{"diff_url":null,"patch_url":null,"html_url":null},"body":"Scope of Change\n====\nThis RFC defines the standards for the XP runners.\n\n\nRationale\n====\nClarification is needed.\n\n\nFunctionality\n====\nXP runners make it easy to run XP classes.\n\nHello World-Example\n----\nHello.class.php:\n\n```php\n<?php\n  uses('util.cmd.Console');\n  \n  class Hello extends Object {\n  \n    public static function main(array $args) {\n      Console::writeLine('Hello ', $args[1]);\n    }\n  }\n?>\n```\n\nTo run this code with php, we would have to type:\n\n```\n  $ php\n  > -dinclude_path=\"/path/to/xp:/path/to/xp/xp-rt-X.X.X.xar:.\"\n  > -dauto_prepend_file=\"lang.base.php\"\n  > -r \"uses('Hello'); Hello::main($argv);\"\n  > World\n\n```\n\nIf we use the XP runner, we simply type:\n\n```\n  $ xp Hello World\n\n```\n\n\nBoot classpath\n----\nThe boot classpath consists of the following entries:\n\nRelease:\n* /path/to/xp - where lang.base.php resides\n* /path/to/xp/lib/xp-rt-X.X.X.xar - runtime XAR\n* /path/to/xp/lib/xp-net.xp_framework-X.X.X.xar - tools and tests\n\nDev:\n* /path/to/xp/skeleton - where lang.base.php resides\n* /path/to/xp/ports/classes - where net/xp_framework is\n\nThese files compose the essentials of the XP framework.\n\n\nPath files\n----\nInspired by a little-known feature in Python (`.pth`-files), the\nXP framework loads path files (which contain a list of paths, each on a\nline by itself) and adds them to `include_path`.\n\n\n```\n  # boot.pth from a released version\n  ../\n  ../lib/xp-rt-5.6.7RC1.xar\n  ../lib/xp-net.xp_framework-5.6.7RC1.xar\n\n```\n\nPaths inside `.pth` files are expanded relative to the file they\nare contained in. The special tilde character (`~`) may be used\nto reference the home directory (`getenv HOME` on Un*x and Cygwin, \n`getenv HOMEPATH` on Windows).\n\nPath files are searched for in the following locations:\n* The directory the runners exist in (`dirname $0`/*.pth)\n* The current directory (`pwd`/*.pth)\n\nOrder in path files is significant - paths will be added to the classpath\nin the order they appear inside the file!\n\n\nReleased versions\n----\nEvery release comes bundled with the runners:\n\n\n```\n  + xp-VERSION/\n    +- lang.base.php\n    +- lib/\n    |  +- xp-rt-VERSION.xar\n    |  +- xp-net.xp_framework-VERSION.xar\n    |  +- ... (further xar files)\n    +- bin/\n       +- boot.pth\n       +- xp\n       +- xpcli\n       +- ... (further utilities)\n\n```\n\nThe runners all use `../lang.base.php`, `../lib/xp-rt-VERSION.xar` \nand `../lib/xp-net.xp_framework-VERSION.xar` to ensure no global \n`include_path` setting will \"disturb\" the class loading process. \nAssume you have installed the XP framework to `/usr/local/lib`. \nBy adding `/usr/local/lib/xp-VERSION/bin` to your `PATH`, you can \ntype \"xp\" in any shell to invoke the xp utility. \n\nTo add XAR files to the class path temporarily, you can use the \"-cp\" option, \ne.g. `xp -cp \"/path/to/thekid.xar\" de.thekid.Hello` or \n`xp -cp \"/path/to/classes\" de.thekid.Hello`. To permanently add paths or \nxar files to the classpath, create a file containing these and save it\nto /path/to/xp-VERSION/bin/. Its name is irrelevant, though it must end in \".pth\".\n\n\nDevelopment checkout\n----\nFor a development checkout (needed for developing the XP framework itself), the \ndirectory tree looks as follows:\n\n\n```\n  + trunk/\n    +- skeleton/\n    |  +- lang.base.php\n    |  +- lang/\n    |  |  +- Object.class.php\n    |  |  +- ... (lang package contents)\n    |  +- ... (packages)\n    +- ports/\n       +- classes/\n       |  +- net/\n       |  +- ... (further non-core classes)\n       +- technologies/\n          +- env/\n             +- bin/\n                +- xp\n                +- xpcli\n                +- ... (further utilities)\n\n```\n\nBecause the env/bin directory contains the \"raw\" form of our utilities, \nit is required that the platform-specific versions be setup in another \ndirectory, for example as follows:\n\n\n```\n  + xp\n    +- bin\n    |  +- boot.pth\n    |  +- xp\n    |  +- xpcli\n    |  +- ... (further utilities)\n    +- trunk/\n       +- ... (see above)\n\n```\n\nThe boot.pth file would contain:\n\n\n```\n  ../trunk/skeleton\n  ../trunk/ports/classes\n\n```\n\nAnother setup (if you don't mind you ~/bin/-directory being \"cluttered\"\nwith XP binaries):\n\n\n```\n  + ~\n    +- bin/\n    |  +- boot.pth\n    |  +- xp\n    |  +- xpcli\n    +- devel/\n       +- xp/\n          +- trunk/\n             +- ... (see above)\n\n```\n\nThe boot.pth file would contain:\n\n\n```\n  ../devel/xp/trunk/skeleton\n  ../devel/xp/trunk/ports/classes\n  \n  # or (because it's equivalent in this case)\n  ~/devel/xp/trunk/skeleton\n  ~/devel/xp/trunk/ports/classes\n\n```\n\n\nProject Development and the classpath\n----\nIf you are developing applications ontop of the XP framework, you probably\nhave the following directory layout:\n\n\n```\n  + PROJECT\n    +- lib/\n    |  +- app-specific.xar\n    |  +- ... (further supporting libraries)\n    +- classes/\n    |  +- de/\n    |     +- thekid/\n    |        +- SomeClass.class.php\n    |        +- ... (further classes and packages)\n    +- ... (further project-specific directories, e.g. xsl or doc_root)\n\n```\n\nIn a slightly different setup, we'd have a \"common\" libdir:\n\n\n```\n  + xp/\n    +- common/\n    |  +- lib/\n    |     +- supporting.xar\n    |     +- ... (further supporting libraries)\n    +- projects/\n       +- PROJECT\n          +- lib/\n          |  +- app-specific.xar\n          |  +- ... (further app-specific libraries)\n          +- ... (further project-specific directories)\n\n```\n\nTo add the \"classes\" directory and the xars in \"lib\" (and \"common/lib\") to \nyour classpath, add a path-file to the PROJECT directory (from which the \nwork will be done):\n\n\n```\n  # development.pth\n  classes/\n  lib/app-specific.xar\n  \n  # For the common/lib-case, add\n  ../../common/lib/supporting.xar\n\n```\n\n\nReleased projects and the classpath\n----\nThe above project is released in a XAR file, and all libraries it depends\non are bundled:\n\n\n```\n  + PROJECT-VERSION\n    +- lib/\n    |  +- PROJECT-VERSION.xar\n    |  +- supporting.xar\n    |  +- app-specific.xar\n    |  +- ... (further supporting libraries)\n    +- ... (further project-specific directories, e.g. xsl or doc_root)\n\n```\n\nTo add the \"PROJECT-VERSION.xar\" and all other xars in the \"lib\" directory \nto your classpath:\n\n\n```\n  # release.pth\n  lib/PROJECT-VERSION.xar\n  lib/app-specific.xar\n  lib/supporting.xar\n\n```\n\n\nFramework*2\n----\nDeveloping an internal framework ontop of the released XP framework \nyou'd have a directory layout as follows:\n\n\n```\n  + xp/\n    +- classes/\n       +- com/\n          +- oneandone/\n             +- session/\n             |  +- Session.class.php\n             |  +- SessionProtocol.class.php\n             |  +- ... (further classes and packages)\n             +- SomeClass.class.php\n             +- ... (further classes and packages)\n\n```\n\nFrom this directory, the XARs in the common/lib directory would be created.\nWhile developing, it is easier to have the xp/classes directory in your\nclasspath; to add it, add the directory to your XP installation. \n\nAssuming the xp-directory from above is in `/home/thekid/devel/xp` and\nthe public XP framework installed in `/usr/local/lib/xp-VERSION` and \nyou are fine with allowing this for all users:\n\n\n```\n  # /usr/local/lib/xp-VERSION/bin/com.1and1.pth\n  ~/devel/xp/classes/\n\n```\n\n\nWebsites\n----\nWhen running inside a webserver via PHP's Apache Module, the runners aren't\ninvoked. The boot classpath must be set from within the web server \nconfiguration. Here's an example for apache (on Windows):\n\n\n```\n  <VirtualHost localhost:80>\n    RewriteEngine on\n    RewriteRule !^/static /index.php\n\n    DirectoryIndex index.php\n    DocumentRoot c:/cygwin/home/thekid/dialog/doc_root/\n\n    # Boot classpath\n    php_value include_path \".;d:/share/xp-5.7.0;d:/share/xp-5.7.0/lib/xp-rt-5.7.0.xar\"\n  </VirtualHost>\n\n```\n\nThe index.php file is a generic file:\n\n```php\n<?php\n  require('lang.base.php');\n  xp::sapi('web');\n  \n  scriptlet::run(__FILE__);\n?>\n```\n\nIt determines the class path from `[DOCUMENT_ROOT]/../WEB-INF/web.ini`.\n\n```\n  ; Dialog web configuration\n\n  [application]  \n  class-path=\"../lib/dialog-2.4.0.xar\"\n\n  [/xml]\n  package=\"de.thekid.dialog.scriptlet\"\n\n```\n\n\nCore utility: xp\n----\nBasic runner\n\n```\n  # Display version\n  $ xp [opt] -v\n\n  # Evaluate\n  $ xp [opt] -e 'echo create(new Object())->hashCode();'\n  \n  # Run main class from xar file (via META-INF/manifest.ini)\n  $ xp [opt] -xar [app.xar]\n  \n  # Run class\n  $ xp [opt] class.with.static.main.Method\n  \n  opt is one of:\n  * -cp [path-list] - Set classpath\n\n```\n\n\nCore utility: xpcli\n----\nThe xp command class runner. An alias for `xp util.cmd.Runner`.\n\n```\n  # Runs class by fully qualified name\n  $ xpcli class.which.extends.util.cmd.Command\n  \n  # Runs class by filename\n  $ xpcli class/which/extends/util/cmd/Command.class.php\n\n```\n\n\nCore utility: xar\n----\nWorks with XAR archives. An alias for `xp net.xp_framework.xar.Xar`.\n\n```\n  $ xar [instruction] target.xar [file-or-directory*]\n  \n  instruction is one of:\n  * c[v]f - Create\n  * x[v]f - Extract\n  * t[v]f - List\n  * s[v]f - Show\n  \n  file-or-directory is one of:\n  * a directory - all files and directories in the directory will be added\n  * a file - the file will be added\n\n```\n\n\nDevelopment utility: n\n----\nStarts editor.\n\n```\n  $ n [class-or-file*]\n  \n  class-or-file is one of:\n  * fully.qualified.class.Name\n  * fully/qualified/class/Name.class.php\n\n```\n\n\nDevelopment utility: unittest\n----\nRuns classes that extend the unittest.TestCase class. An alias for \n`xp net.xp_framework.unittest.runner.cli.CliRunner`.\n\n```\n  $ unittest [class-or-config*]\n\n  class-or-config is one of:\n  * class.which.extends.unittest.TestCase - a fully qualified class name\n  * class/which/extends/unittest/TestCase.class.php - a filename\n  * unittests/config.ini - a property file\n\n```\n\n\nDevelopment utility: doclet\n----\nRuns doclets.\n\n```\n  $ doclet class.which.extends.text.doclet.Doclet\n\n```\n\n\nDevelopment utility: qnt\n----\nRuns Quantum buildfiles (`build.cxml`).\n\n```\n  $ qnt [target]\n\n```\n\n\nDevelopment utility: cgen\n----\nCode generator utility.\n\n```\n  # Generate parsers\n  $ cgen [options] Parser <grammar> <skeleton-name> <parser-name>\n  \n  # Generate remote stubs via ESDL\n  $ cgen [options] Stubs [dsn]\n  \n  # Generate datasets\n  $ cgen [options] DataSets [dsn]\n  \n  options is one of:\n  * -o dir/: Generate class files to directory dir/ (default: ./)\n\n```\n\n\nDevelopment utility: xcc\n----\nCompiles XP sourcecode to bytecode.\n\n```\n  $ xcc any/source/File.xp\n\n```\n\n\nDevelopment utility: opcodes\n----\nDumps opcode instructions from compiled bytecode.\n\n```\n  $ opcodes any/compiled/File.xpc\n\n```\n\n\nSecurity considerations\n====\nNone.\n\n\nSpeed impact\n====\nNone.\n\n\nDependencies\n====\nNone.\n\n\nRelated documents\n====\n* [http://mindprod.com/jgloss/classpath.html classpath Java Glossary]\n* [http://bob.pythonmac.org/archives/2005/02/06/using-pth-files-for-python-development/ Using .pth files for Python development]\n\n\n","comments":4,"title":"XP Runners","updated_at":"2011-10-17T16:02:18Z","url":"https://api.github.com/repos/xp-framework/rfc/issues/166","id":1930320,"assignee":null,"milestone":null,"closed_at":"2011-10-17T16:02:14Z","user":{"gravatar_id":"26f07e3b262e9a80436f368cb11bd0c2","avatar_url":"https://secure.gravatar.com/avatar/26f07e3b262e9a80436f368cb11bd0c2?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png","url":"https://api.github.com/users/thekid","id":696742,"login":"thekid"},"html_url":"https://github.com/xp-framework/rfc/issues/166","labels":[{"name":"framework","url":"https://api.github.com/repos/xp-framework/rfc/labels/framework","color":"118f5b"},{"name":"implemented","url":"https://api.github.com/repos/xp-framework/rfc/labels/implemented","color":"807370"}],"state":"closed"},"legacy":{"issue_id":1930320,"comment_id":2430824}}