**************************************************************************
** title:      Pods
** author:     Brian Frank
** created:    24 Jul 09
** copyright:  Copyright (c) 2009, Brian Frank and Andy Frank
** license:    Licensed under the Academic Free License version 3.0
**************************************************************************

Overview [#overview]
********************
Pods are the top of Fantom's namespace as well as the unit of deployment.  A
pod's name is globally unique and is used to organize the top level of Fantom's
namespace.  In this respect pods serve the purpose of both a Java package and
a JAR file (or .NET namespace and DLL).

Pod Meta [#meta]
****************
Pods do not use `Facets` for metadata like types and slots.  Rather pod metadata
is managed as name/value pairs.  Key metadata about your pod is defined in
the [build script]`docTools::Build#buildPod`:

  class Build : build::BuildPod
  {
    new make()
    {
      podName = "myPod"
      summary = "Summary description of my pod"
      depends = ["sys 1.0", "web 1.0"]
      meta    = ["acme.sku": "0xdeadbeef"]
      srcDirs = [`fan/`]
      resDirs = [`locale/`]
    }
  }

During the build process fields like 'podName' and 'depends' are used by the
compiler to generate the pod's metadata.  You can define your own additional
name/value pairs with [BuildPod.meta]`build::BuildPod.meta`.  Plus the compiler
will add its own metadata regarding when and where the pod was built.

Metadata is stored "/meta.props" in the pod zip file. The [Pod.meta]`sys::Pod.meta`
method is used to access a pod's metadata at runtime.

The following are the standardized user defined keys:
  - 'org.name': name of the organization who developed the pod;
    the name should be a unique string name used consistently across all pods
  - 'org.uri': web site URL of the organization
  - 'proj.name': name of the project which groups one or pods;
    should be a unique string name used consistently across all pods
  - 'proj.uri': web site URL of the project
  - 'license.name': name of the license used by the project which should
    be "Commercial" or one of the long names defined by
    [OSI]`http://www.opensource.org/licenses/alphabetical`
  - 'vcs.name': name of the version control system: "Mercurial", "Git", "Subversion"
  - 'vcs.uri': URI of the public version control repository

The following are the standardized keys automatically defined by compiler:

  - 'pod.name': name of the pod
  - 'pod.version': [Version]`sys::Version` of the pod
  - 'pod.depends': list of semicolon separated [Depend]`sys::Depend` strings
  - 'pod.summary': overview decription for pod
  - 'pod.isScript': was the pod compiled in script mode
  - 'pod.docSrc': should documentation include source code, see [BuildPod]`build::BuildPod.docSrc`
  - 'pod.docApi': should pod be included in documentation, see [BuildPod]`build::BuildPod.docApi`
  - 'pod.native.java': does pad use native Java code (true or false)
  - 'pod.native.dotnet': does pad use native .NET code (true or false)
  - 'pod.native.js': does pad use native JavaScript code (true or false)
  - 'fcode.version': binary format version of the fcode
  - 'build.ts': compile time in local timezone formatted as [DateTime]`sys::DateTime.toStr`
  - 'build.platform':  compile env platform formatted as [Env.platform]`sys::Env.platform`
  - 'build.host': compile env host name, see [Env.host]`sys::Env.host`
  - 'build.user': compile env user name, see [Env.user]`sys::Env.user`
  - 'build.compiler': compiler pod version

