Skip to content

fep-0001.md

Latest commit

 

History

History
229 lines (175 loc) · 6.84 KB

fep-0001.md

File metadata and controls

229 lines (175 loc) · 6.84 KB

FEP 1: fan build command line tool

Author:   Andy Frank
Status:   Active
Created:  10-Sep-2018
Modified: 17-Sep-2018

Summary

The fan build tool is designed to simplify starting new Fantom projects, as well as handle boiler-plate and scaffolding-type code and directory generation.

Goals

  • Create a new command line tool to:
    • Stub a new PathEnv project directory and supporting files
    • Stub a new pod source tree and supporting files
  • Officially recommend new projects be created in their own PathEnv
  • Enhance docIntro chapter to utilize fan build in examples

Non-Goals

This proposal does not attempt to formalize the role and function of the fan.props file outside of creating a PathEnv.

Motivation

The default behavior of Fantom is to install compiled pods into the global lib/ folder. However most modern projects utilize PathEnv to organize their code separately. While the processes for accomplishing this are documented, this is not explicitly recommended, nor is there any comprehensive examples.

A lesser problem is there exists a fair amount of boilerplate to create both new PathEnv folders and creating new source trees for pods within these projects. This results in either copy-and-pasting files from other projects, and/or setting up IDE macros.

This proposal aims to solve both problems by introducing a new command line tool that is easy to understand and use for both beginner and expert users.

In addition, several new FEP's will depend on PathEnv configuration, so this is a foundational FEP for future Fantom enhancements.

Description

A new build::Main class will be created with the follwing command:

# create new PathEnv and pod source tree
fan build init <pod-name>

It was considered whether these commands should be created in a new top-level pod (such as init), which could support future functionality and possibly APIs for adding features downstream.

That remains a viable path, however, it is outside the scope of this FEP. This enhancement is focused on adding only the core needs to bootstrap new Fantom projects. By bundling these tools in the build pod we allow both new and third party tools space to create, enhance (and even deprecate) the standard init tools.

Directory Structure

This proposal standardizes the following directory structure for Fantom projects:

project/                 # top-level project name
│
├── fan.props            # file to trigger PathEnv
├── etc/                 # project local etc/ dir
├── lib/                 # project local lib/ dir
└── src/                 # project local src/ dir
    │
    ├── build.fan        # top-level BuildGroup script
    │
    └── podA/            # podA: source sub-directory
    │   ├── build.fan    # podA: build script
    │   ├── fan/         # podA: fan source directory
    │   └── test/        # podA: test source directory (optional)
    │
    └── podB/            # podB: source sub-directory
        ├── build.fan    # podB: build script
        ├── fan/         # podB: fan source directory
        └── test/        # podB: test source directory (optional)

The init Command

This is the default mechanism used to create new "projects".

Example use:

$ fan build init hello
Created new env 'hello/'
Created new pod 'src/hello/'
INIT SUCCESS!

Example output (created under current working dir):

hello/
├── fan.props
├── etc/
├── lib/
└── src/
    ├── build.fan
    └── hello/
        ├── build.fan
        ├── fan/
        └── test/

Several directories and files are created:

  1. A top level hello/ project directory

  2. fan.props: an empty file that tells Fantom this folder is a new PathEnv

  3. Directory stubs for etc/, lib/, and src/

  4. A directory stub src/hello/ for a hello pod with associated build.fan script

  5. A top level build.fan BuildGroup script

NOTE: No source files are created in this process.

By default a single pod is always created that matches the project name. If additional pods are needed, run the init command under the project directory with the desired pod names:

$ cd hello
$ fan build init world
Created new pod 'src/world/'
Remember to add 'world/build.fan' to 'src/build.fan'!
INIT SUCCESS!

Example output:

hello/
├── fan.props
├── etc/
├── lib/
└── src/
    ├── build.fan
    ├── hello/
    │   ├── build.fan
    │   ├── fan/
    │   └── test/
    └── world/
        ├── build.fan
        ├── fan/
        └── test/

Note you will need to manually add the new world/build.fan script to the top level build.fan script.

BuildGroup build.fan Script

The proposal specifies that all Fantom projects contain a top-level build script under src/build.fan. The default script generated will include the inital pod. As new pods are added, they need to be manually added to this script.

#! /usr/bin/env fan

using build

class Build : BuildGroup
{
  new make()
  {
    childrenScripts =
    [
      `hello/build.fan`,
    ]
  }
}

Pod build.fan Scripts

The init command will generate a minimial build.fan script for each pod it creates. This script will document what configuration and meta-data a developer may want to add:

#! /usr/bin/env fan

using build

class Build : build::BuildPod
{
  new make()
  {
    podName = "hello"
    summary = "Description of this pod"
    version = Version("1.0")
    // These values are optional, but recommended
    // See: http://fantom.org/doc/docLang/Pods#meta
    // meta = [
    //   "org.name":     "My Org",
    //   "org.uri":      "http://myorg.org/",
    //   "proj.name":    "My Project",
    //   "proj.uri":     "http://myproj.org/",
    //   "license.name": "Apache License 2.0",
    //   "vcs.name":     "Git",
    //   "vcs.uri":      "https://github.com/myorg/myproj"
    // ]
    depends = ["sys 1.0"]
    srcDirs = [`fan/`]
    // resDirs  = [,]
    // javaDirs = [,]
    // jsDirs   = [,]
    // docApi   = false   // defaults to 'true'
    // docSrc   = true    // defaults to 'false'
  }
}

Enhance Documentation

As part of this propoal, we also want to update our documention to indicate using init is the standard method for creating new Fantom projects.

Two sections will be updated, the first in docIntro::HelloWorld. Here will mostly maintain the existin content, but rework the examples to use init:

$ fan build init hello

The second will be to add a new section to docTools::Build describing the init command tool usage and behavoir.