Pods

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

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:

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. 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 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
• vcs.name: name of the version control system: "Mercurial", "Git", "Subversion"
• vcs.uri: URI of the public version control repository
• doc.format: format used for the pod's documentation; set to "markdown" to author type/slot doc comments and chapter files in markdown. See Documentation

The following are the standardized keys automatically defined by compiler:

• pod.name: name of the pod
• pod.version: Version of the pod
• pod.depends: list of semicolon separated 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
• pod.docApi: should pod be included in documentation, see BuildPod
• pod.js: does pod include client side JavaScript code (true or false)
• pod.native.java: does pod use native Java code (true or false)
• pod.native.dotnet: does pod use native .NET code (true or false)
• pod.native.js: does pod 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
• build.platform: compile env platform formatted as Env.platform
• build.host: compile env host name, see Env.host
• build.user: compile env user name, see Env.user
• build.compiler: compiler pod version

Documentation

Pod documentation is authored in two places:

• type/slot docs: the ** doc comments on your types and slots
• chapters: standalone files under the pod's "doc/" directory, plus an optional pod-level doc named "doc.md" (historically "pod.fandoc") as a peer of the build script

Fantom documentation uses a flavor of markdown called xetodoc:

• formally based on Commonmark
• link shortcuts for types and slot names such as [Str]
• Github style heading anchors
• Github style tables
• Nested HTML is disallowed

New pods should author all doc comments and chapters in markdown and opt-in by adding doc.format to the build script meta:

meta = ["doc.format": "markdown", ...]

Historically Fantom documentation used fandoc, a wiki-style markup. The two formats differ in key ways:

• links use markdown syntax [text](uri) and the shortcut [uri] instead of fandoc's backtick `uri`
• inline code uses backticks `code` instead of fandoc's single quotes 'code'
• code blocks use fenced ``` blocks instead of pre>/<pre>
• headings use # prefixes instead of underlines, and anchors are derived from the heading text (github style) rather than explicit [#id] ids

When doc.format is absent the legacy fandoc renderer is used for backward compatibility. Use the adm/fandoc2md.fan script to convert existing fandoc sources to markdown.