Skip to end of metadata
Go to start of metadata
RFC CLOSED

This RFC is closed for comments.

Synopsis

Currently, we have a suite of existing tools for operating from the command line - titanium.py, builder.py, etc. Some of these tools are intended for direct user interaction to create, run, package, or distribute projects (titanium.py) and some of them are designed for meaningful interactions only with an IDE such as Studio.

Over time, due to the addition of features and bug fixes, maintaining these build scripts has become progressively more difficult and users have come up with stories which require a rethinking of the structure of the build system itself. Additionally we often have requests from the studio team to add new features which would be cumbersome to add, or simply difficult to integrate, into the existing infrastructure.

This document is intended to outline specific problems with the existing command line interface (CLI) and certain components used by it which are tightly coupled with Titanium Studio, and propose a specification which is intended to resolve them while remaining extensible.

Justification

The following is a brief overview of the highest-level problems facing our existing command line tooling.

Decoupling CLI from platform

The most useful thing we get out of a refactoring of the existing command line system, and redesigning it, is that we would be able to separate the tooling from the platform. This means that we can independently version these products, which will allow for better integration with Studio releases, a way to rapidly respond to tooling bugs and features, and prevent some issues which currently occur with SDK versioning (feature X is available in 1.8.0.1, but not 1.7.5, so if you downgrade your app - or even created it with the wrong version - you may lose functionality.) This is especially problematic for modules, which must be recreated to take advantage of any module building upgrades in SDK versions.

Drillbit integration

Although we do not currently have a drillbit specification at this time, it is expected that Drillbit will integrate with the new CLI in some manner. Furthermore, we would be able to develop a robust testing infrastructure for the CLI which would help us detect bugs and critical regressions.

Additionally, integrating Drillbit or other testing functionality into our CLI enables users to write their own unit tests, a feature that has been requested for some time and may alleviate some problems that external test frameworks cause for our platforms.

Fragility

Our build system is extremely fragile. Making changes to the main build system in the past has broken critical features such as: module creation, module building, and transport (export to standalone Xcode project) in the past. The lack of testing infrastructure and codependence upon many moving, large parts means that these bugs easily slip through.

Adding new features or fixing bugs in the past has, as well, caused fragility problems. Rather than improving the source base, these tend to be "quick fixes" that are encouraged by the mindset that the build scripts are not in a maintainable state and so there is no incentive to introduce maintainability with the system's present state.

Naturally, this also makes it difficult to fix bugs.

User stories

From community and the Studio team, we are frequently getting requests for more and more features (see Fragility above, and Extensibility, below.) As testing and build systems for mobile get more sophisticated, we should be expected to be inundated with requests. Some of these user stories are contained within TIMOB-8662, the specification requirements.

Many users also wish to avoid Studio, whether out of personal preference or the lack of suitability for automated or staged builds. Our current command line tools are woefully inadequate for these purposes; they lack documentation and functionality, and to take advantage of the build system directly, users are required to automate with builder.py which is unintuitive even to the platform team.

Extensibility

Currently, it is very difficult to add new features to our build scripts. Although we can always add new commands, doing so is cumbersome on both Android and iOS, requiring unintuitive modifications to the build system in places. Modifying existing commands can be even more difficult; there are many which tie into each other in unexpected ways in iOS due to the poor way the existing source is structured.

Adding options to existing commands is even more difficult. Currently Android's builder.py takes up to 10 command line arguments; iOS takes 9. These command line arguments are not named and there are no switches; these are all raw text and there is no documentation about what any of them do beyond the source.

Business requirements

Appcelerator is currently messaging as a one stop javascript shop, meaning that having our tooling infrastructure written in languages which are not javascript is no longer considered appropriate. Customers expect to be able to interact with our product via javascript at all levels.

Definitions

  • CLI: Command Line Interface. The frontend with which users will interact with the tooling system.
  • Tooling: The complete set of build scripts and associated tools which both the CLI and Titanium Studio will interact with to perform tasks related to the platform.
  • Platform: Titanium Mobile as a whole, not a specific mobile platform. This is a distinct product from the CLI.
  • builtin: A command "built in" to the CLI, either as a command that is directly bundled with the CLI frontend itself, or is guaranteed to distribute with the CLI. These commands are considered foundational and critical to the Titanium workflow.
  • external: A command which is "external" to the CLI. These commands may or may not be distributed with the CLI frontend, and will all be external scripts or programs. Users are allowed to create their own externals.

Proposed specification

The following specification is based upon the requirements laid out in TIMOB-8662.

Language requirements

The following assumes that the CLI itself, as well as all tooling, will be written in node.js. See the following tickets:

As a result some requirements for engineering are included in the descriptions of various components.

What if node.js is already installed on somebody's system? Can we lock a version? Does studio need to autoupdate it?

These are all good questions. node.js currently exists in a state where most of their APIs are at level 3 (Stable) or higher (Frozen, Locked). We can distribute a "locked" version (at this time, v0.6.17) with Studio, but any updates to node (and it does move rapidly) will require a vetting of the CLI, all builtins, and all official externals by engineering (and possibly QE) before we can push an update. There may be times where this becomes critical due to a bad release of node. As a result we must only lock versions which are known to be stable and lack bugs which affect CLI builtin operation.

A bigger concern is developers taking advantage of node features outside of this locked version. We can alleviate this by requiring versioning with commands, as npm currently does with packages. See versioning, below. The only commands which are forced to be both minimum-compatible and maximum-compatible with the locked version are builtins. Note that this may introduce version incompatibilities where externals will require a version of node which may not interoperate well with the builtins, and we should make developers aware of what the distributed "locked" version is so they can plan and operate accordingly.

Frontend (CLI)

The goal of the CLI frontend is to create a flexible, well-defined lightweight tool which interacts well with the tooling. Because of the desired modularity of components, the proposal is that the CLI itself be as small as possible, and serve primarily as a routing tool to individual components.

In order to accomodate this, the CLI will route commands to smaller, more specific scripts which will be loaded via require(). This gives us the following:

  • Easy extensibility
  • Strong plugin support
  • Independent versioning/updating of individual commands if required
  • Separation between "builtins" and "extensions"
  • Lightweight frontend

Paths

For a configurable tool, the CLI will need to check certain paths for commands, pre/post hooks, command options, etc. The following is the chain in which the CLI checks for availability for these:

  • Command-line options (if available)
  • User's $ENV (if appropriate)
  • $PROJECT_DIR/.titanium
  • $HOME/.titanium
  • /usr/local/titanium

These paths are for UNIX-like systems only. On Windows we expect to use equivalent (but different) paths. Directories will still be named .titanium.

Platform-specific data

We will no doubt have a few commands (or maybe even manifests/configurations) which are either platform-specific, or are required to have platform-specific components. In this case, we need to make sure they are called out to correctly, either by a generic frontend command in .titanium or directly via the CLI. For this reason, .titanium will contain a subdirectory for each platform, which will contain platform-specific commands or manifests.

Configuration

The CLI will get some basic configuration information from a config file (such as $HOME/.titanium/config), which will contain information such as the location of platform SDKs, the Android SDK and NDK install, the xcode developer tools location, and other salient information such as default log level.

Note that this configuration file is intended to be used by the CLI only - Studio may maintain its own set of configurations, which can be communicated to the tooling via environment variables or some other method. This configuration file is also distinct from tiapp.xml. In general:

  • If a property for a project relates to project building or creation only, it is part of the CLI config file.
  • If a property takes advantage of an SDK feature (such as runtime), or is otherwise used aside from project build/create, it is part of tiapp.xml.

In particular this may affect the current mobileweb proposal for a <build> segment in tiapp.xml.

Format

There has been some discussion about the format of the config file for the CLI, and the initial determination is that it should be a JSON format file, for easy portability between development tools and processing. The file format will probably be something like:

Config format

Each platform defines its own constants in the config. These properties are referred to on the command line not with dictionary notation (titanium['sdk']) but rather with dot notation (titanium.sdk) which makes things easier on shell parsers. We intend for these values to correspond to ENV settings where possible, again for shell compatibility. Some examples of what might be considered acceptable property names, and their intent, are:

  • android.sdk - Android SDK location
  • android.ndk - Android NDK location
  • ios.tools - Path to the Developer tools
  • ios.signing_certificate - Signing certificate ID for iOS
  • titanium.sdk - Location of the titanium SDK install(s)
  • titanium.sdk_version - Default SDK version to use

Note that somewhere between "no" and "few" properties should be required. We should provide sensible defaults where possible.

Hook support

All commands will support pre- and post- hooks. These will be placed in a common directory such as $HOME/.titanium/hooks/[pre|post]-[command].[ext], the SDK or tooling itself, or even be on a per-project basis. The idea is that a hook will be named after the command it is intended to be executed either before or after, and will be able to abort the process if it is a pre-hook.

Hooks must also be written in node.js and are loaded via require() mechanisms. This is to greatly simplify the problem of running synchronous child processes in node.

Tooling versioning

We should keep in mind that versioning is a primary goal for allowing independent commands for tooling. This means that certain tools may require certain versions of other tools, users may want to specify a particular version of a tool to run via the CLI, etc.

We would consider offering a --version requirement for commands, or even an available API hook for the CLI to check, but we cannot guarantee that user-written tools (or even our own externals) will support these features, or they could easily be accessed from a CLI implementation. Instead, we use the npm manifest format. Note that updates to the npm manifest may break Titanium commands as a result.

We do impose the additional requirement that version-spec above is one of the npm version types listed from the format, with the exception that we only support OSGI versioning.

So is the CLI also a package manager?

Unlikely. The CLI will probably use npm as a backend for package management, but support to call out to npm via the CLI will probably be included (see the update external below).

Exit codes

The following are a list of standard exit codes for CLI invokes (in addition to some standard exit codes:

code

description

0

No error

1

Indicates a generic command error (no exit code specified)

2

Command not found

3

Version not found

4

Malformed manifest for command

5

Dependency error

Error codes outside of these values are reserved for specific commands to define.

Universal arguments

Each command should be able to handle the following arguments:

argument

description

default

-h, --help

Prints a help message

-Dkey=value

Defines a config constant key for this run, with value

--version=OSGI_version

Which version of the command to run (if available)

Latest available

--[no]-analytics

Whether or not to send anonymous analytics data for CLI usage.

true

CLI frontend command

The CLI frontend itself can either run a command, or take a generic argument describing the CLI frontend itself. All options and command names are mutually exclusive.

Command

argument

description

command

Command name to run

--version

Prints version information for frontend

Builtins

"Builtins" are tooling that is distributed with the CLI, possibly with some sort of API to allow extension tools to interface with them without having to call the titanium script again. To be clear: Builtins are individual scripts, with their own runtimes, contained within the .titanium directory (perhaps the CLI will pull them from a repo when running for the first time, or otherwise auto-update them, as suggested above.) The following commands are builtins:

  • create
  • available
  • build
  • install
  • run
  • clean
  • help

NOTE: All builtins are expected to have a --help option which prints a brief description of the command and the arguments. Because everything supports this, it is not listed in the arguments for each individual command.

create

This command is used for the creation of new projects or modules.

Command

option

description

default

-p,--platforms

The platforms for the project. ios is a synonym for iphone,ipad.
note: For modules, only one platform can be specified.

None

-t,--type

The type of project to create. One of: app (application), module

app

-i,--id

The project ID.

Derived from the project name and id.prefix setting.
note: If id.prefix is unset, required.

-s,--sdk

The platform SDK version to use for generating the project contents.

titanium.sdk

-v,--verbose

The verbosity level of output. -v alone corresponds to DEBUG [4].
Uses numeric values only, not mnemonics.

titanium.log_level

--template

Name of template to use.

Default template for provided SDK.

-c,-[no]cloud

Whether or not to automatically cloud-enable the application.

true

-d,--dir

Directory to place the project in.

name

arguments

description

name

Name of the project to create. This creates a directory with this name unless --dir was specified, and copies the relevant templates from the SDK into it.

Dependencies

create may call out to the available builtin to determine if certain platforms, or possibly future project types, are available in the provided version of the SDK.

available

This feature is intended to detect whether or not certain functionality is available in various versions of the CLI, tooling, or SDK. This provides a tool which Studio has requested to detect feature availability, and is usable as a subtask by other builtins (or externals) to determine supported features.

Because this command performs SDK feature detection, it could be considered fragile - for example, if it detects platform availability based on directory structure, if the SDK changes that directory structure at any time, the CLI/tooling will become incompatible with that version.

Specifying how the SDK advertises "available" features and platforms may be considered outside of the scope of this specification, but we expect that it will likely be based on a manifest.

Command

Note that only one of --command, --feature, or --platform should be used.

option

description

default

-c,--command

Tests for availability of name as a titanium command.
note: This functionality should be able to be duplicated by having titanium return a standard nonzero exit code.
As a result this option may be removed.

false

-f,--feature

Tests for availability of name as a feature of the given SDK.

true

-p,--platform

Tests for availability of name as a platform of the given SDK.

false

-v,--version

Checks for a specific version of the requested command/feature/platform.

None

-s,--sdk

The SDK to check.

titanium.sdk

arguments

description

name

The name of the feature/command/platform to check for.
note: We will need some way to standardize "feature" names.

build

This command is used to build, but not run or install, a project. Note that what the build command does is slightly different based on whether the project is a module or an app.

For modules, the build command is intended to replace our existing builder.py script that is bundled with a module.

Command

option

description

default

-p,--platform

The platform to build for. ios is a synonym for iphone,ipad.
note: For modules, this argument is unnecessary and ignored.

First platform listed in tiapp.xml

--package

Packages the project into a submittable binary (app) or a distributable zipfile (module).
*note:* For modules, leaving off this argument compiles sources into a library or JAR only.
*note:* Forces --device for apps, --device and --emulator for modules.

false

--device

Builds the project for device.

false

-simulator,-emulator

Builds the project to run on a development machine.

false

--production

Builds in production mode. Excludes --development.
*note:* Automatically set by --package.

false

--development

Builds in development mode. Excludes --production.

true

-v,--verbose

The verbosity level of output. -v alone corresponds to DEBUG [4].
Uses numeric values only, not mnemonics.

titanium.log_level

NOTE: At least one of -device or --simulator|-emulator is required when --package is not supplied.
NOTE: We will also need to consider device-specific settings, i.e. ios.code_sign.

argument

description

default

project-dir

The directory of the project to build.

cwd

Dependencies

It should be noted that build does not automatically depend on validate - rather than validate, the build will fail at the point where an error is encountered. This is to keep validate as an external, and encourage use of it only to identify problems during migration.

Note that build may internally rely on the same mechanisms used by validate that are provided by the SDK, however, including available and any other SDK metadata.

install

The install command is intended to install - but not run - an application or module that has already been built. note: For iOS, it may not be possible to "just" install an application on simulator without running it. This is a task which would require investigation, and as a result may prohibit iphone,ipad,ios from being valid platforms. Other platforms may also be affected.

Note that what the install command does varies slightly depending on whether the project is an app or module.

Command

option

description

default

-p,--platform

The platform to install for. ios is a synonym for iphone,ipad.
note: For modules, this argument is unnecessary and ignored.

First platform listed in tiapp.xml

--device

Installs the project on a device.
NOTE: For iphone,ipad,ios this may instead "install" to iTunes.
*NOTE:* For modules, this is ignored. See --dir

false

-simulator,-emulator=name

Installs the project on the named simulator/emulator for testing.
*NOTE:* The interpretation of name will vary by platform. For iOS it will be a version, Android an AVD, etc.
*NOTE:* For modules, this is ignored. See --dir

Varies. This depends on the platform.

--dir=dir

Installs the project to the named directory, for modules only (at this time).
*NOTE:* apps ignore this option.

titanium.dir

-v,--verbose

The verbosity level of output. -v alone corresponds to DEBUG [4].
Uses numeric values only, not mnemonics.

titanium.log_level

NOTE: Depending on how we want to treat certain types of iOS adhoc (or other) builds, we may also need to add --package argument support.

argument

description

default

project-dir

The directory of the project to install.

cwd

Dependencies

install depends upon build, but does not automatically invoke it if necessary. Instead the command fails.

run

The run command runs a project. For modules, this runs the sample included with the module.

NOTE: It has been pointed out that for a module sample project, with the build-install-run dependency chain unlocked, "run" would have no defined meaning in this case. Therefore we recommend that modules now have a full application for their sample, which is generated to have the correct tiapp.xml referencing a module load, and the install command for modules may install the module inside of that sample locally. We will need to think about this some more.

Comamnd

option

description

default

-p,--platform

The platform to install for. ios is a synonym for iphone,ipad.
note: For modules, this argument is unnecessary and ignored.

First platform listed in tiapp.xml

--device

Installs the project on a device.
NOTE: For iphone,ipad,ios this may instead "install" to iTunes.
*NOTE:* For modules, this is ignored. See --dir

false

-simulator,-emulator=name

Runs the project on the named simulator/emulator for testing.
*NOTE:* The interpretation of name will vary by platform. For iOS it will be a version, Android an AVD, etc.

Varies. This depends on the platform.

--debug

Runs the debugger in interactive mode with the project. Takes a port to connect on.
*NOTE:* Currently only supported on non-device.

false

-v,--verbose

The verbosity level of output. -v alone corresponds to DEBUG [4].
Uses numeric values only, not mnemonics.

titanium.log_level

NOTE: Depending on how we want to treat certain types of iOS adhoc (or other) builds, we may also need to add --package argument support.

argument

description

default

project-dir

The directory of the project to run.

cwd

Dependencies

run depends upon install, but does not automatically invoke it if necessary. Instead the command fails.

clean

This command cleans a project. This is a builtin to support Studio.

Command

argument

description

default

project-dir

The directory for the project to clean.

cwd

help

This command provides some kind of "help" for other commands. It will likely, like git, direct to a manpage for the specific command if available, or call that command's --help if unavailable. If that is unavailable, it prints the command's description from the manifest. If none of these are available, displays a generic message indicating that the command does not have any help information, and would you please report that to the developer?

Command

argument

description

command

The command to query.

Externals

"Externals" are tooling which may be independent of the CLI distribution, but we will probably have a number of them which ship with it. They are not core tools, but functionality which may be considered useful.

  • test
  • validate
  • migrate
  • lint
  • transport
  • update
  • login / logout

Externals are placed in the .titanium directory. The manifest file for each external is placed there, under the name command.json and used to look up the appropriate command and version, which follows the naming scheme command-version where . characters in the version are replaced with _.

test

This is a placeholder for a command which will invoke drillbit, either for internal or for user-written unit tests.

validate

The validate command is intended to verify that a project conforms to the availability of features in a given SDK, has all of the required settings for that SDK in the tiapp.xml (or other configuration), and checks for deprecated feature usage (and suggests a replacement).

Command

option

description

default

-s,--sdk

The SDK to validate against.

titanium.sdk

-[no]suggest

Whether or not to suggest possible replacements for invalid/deprecated features, or other fixes.

true

-v,--verbose

Verbosity level. -v alone corresponds to DEBUG [4].

titanium.log_level

argument

description

default

project-dir

The directory for the project to validate.

cwd

Dependencies

It is expected that validate will call out to the available builtin.

migrate

This command is intended to migrate a project between SDK versions.

Command

option

description

default

-[no]pre-validate

Run the validate command (with relevant options) on the project to ensure it's valid before performing migration.

false

-[no]post-validate

Run the validate command (with relevant options) on the project to ensure it's valid after performing migration.

true

-v,--verbose

Verbosity level. -v alone corresponds to DEBUG [4].

titanium.log_level

-s,--sdk

The SDK to migrate the project to.

Latest SDK. NOTE: Not default titanium.sdk

argument

description

default

project-dir

The directory for the project to migrate.

cwd

Dependencies

This command will rely on validate as a pre- or post-hook.

lint

This command is a placeholder for a lint-like tool which we could integrate into the CLI. This is a common feature request but requires investigation into available lint-like programs which we might use for JS evaluation, as well as the possibility of rolling our own (to do things like check API correctness).

As a result we do not supply a list of command-line options for lint as it is expected these will depend upon the implementation and requirements for this tool.

export

The export command is intended to be a replacement for our current transport.py script, and operate with platforms other than ios. It creates a standalone project which does not require the Titanium SDK be installed on a system to build, meaning that it distributes important SDK components as part of the export when required.

Command

option

description

default

--platform

Which platform to export the project to.

First platform listed in tiapp.xml

argument

description

default

proejct_dir

The directory for the project to transport.

cwd

update

update exists only as a frontend to npm for updating or installing packages. It pulls them from an Appcelerator-controlled repository which contains tooling. This command is not named install to avoid conflicts with the builtin.

Why isn't update a builtin?

npm is not distributed with all node installs, although we may bundle it with Studio. Making update a builtin would be considered if that's a critical requirement.

login / logout

The login and logout commands are a stub so that we can get some more information about ACS with respect to how the CLI is intended to interact with cloud services. We will certainly require at least these, and may need some additional ACS support as well.

It is expected that the ACS team will be in charge of maintaining and updating these commands, although we will need to collaborate to ensure that they meet the standard CLI argument lists for consistency.

Other possible externals

Based on the fact that build->install->run are commands which do not automagically invoke each other in a chain, we may want a "convenience" command which allows developers to run this chain as an external. We're unsure what a good name for this external would be; suggestions are welcome.

Examples

Standard workflow (app)

Standard workflow (app)

Standard workflow (module)

Standard workflow (module)
Labels
  • None
  1. May 10, 2012

    1. "What if node.js is already installed on somebody's system? Can we lock a version? Does studio need to autoupdate it"
      This can be solved using the following node module that allows for multiple versions of node to be installed and used. You can run the node app for the version you require (ex. $n use 0.3.3 some.js)
      https://github.com/visionmedia/n
    2. Modules
      I think it would be a lot better if common.js modules could also follow more closely to the node_modules system, allowing for multiply javascript files to be used in the module, a few file referencing tweaks (ex. module being required  is done by require('./otherModule') not require('otherModule') and having a package.json file to set module info, configs and paths this would also allow for modules to have custom build scripts to be ran before the titanium builds scripts are executed.
    3. Package Manager
      Since many npm libraries can be easily ported or already available for titanium in npm I think it would be great to just use npm as the default package manager. This would also encourage more devs to make there modules Titanium compatible. When generating a native module for npm we could just link the required build scripts as well. To help with node compatibility implementing a library like https://github.com/seppo0010/nios would help, but that might not be fully feasible.

    Sorry if I went to much off topic in my node.js leg hump haha. Thanks for all the work you guys put in to this platform!!!

  2. May 10, 2012

    I have what should be a common request, as apps need to get more sophisticated. I would like to be able to make a mobile project dependent on a module. Here's my exact scenario right now:

    I have a cross-platform app that requires a custom module on the Android side. Not some existing custom module, one that I needed to develop myself. What ended up happening is I had to go through these steps:

    1. Modify my module
    2. Compile my module project
    3. Copy the module to the mobile project
    4. Compile the mobile project
    5. Test

    It would be far more awesome if I could add my module project as a dependency to my mobile project. This way, I'd only have to modify my module code, and then compile my project... and the project would compile & copy the module if needed.

  3. May 14, 2012

    IMHO - "application" and "module" scripts should be separated.

    There are more reasons why I think that:

    • Most developers are not interested in module development
    • CLI API will be "clearer", which will lead to less confusion and less documentation efforts
    • Maintenance will be easier
    1. May 16, 2012

      Or, at the very least, namespace the module commands.  So, we'll have

         titanium create

         titanium run

      and

         titanium module create

         titanium module run

  4. May 14, 2012

    Please talk with Tony and make sure that whatever he needs for TIMOB-2371 makes it into this new build system!

  5. May 14, 2012

    My notes for this spec are as follows:
    * Justification
    - I agree with the reasons list, I experience some of the same shortcomings.
    - I would add "Customization" as main item; this is the primary feature that most developers are interested in - I see it covered in "Extensibility," however this is the feature that myself and other devs would be most interested in aside from "decoupling"
    - I also use the current CLI for automation purposes. The current scheme is good enough, but I could use these features to make things go smoother:
    == Git integration (currently I script it from commandline)
    == TF or Hockey integration
    == Templating an entire project (currently do simple string subtitution against a settings.js file)
    * Proposed spec
    - Installing node.js can be time-consuming task because of its relative immaturity. Also, different versions of node are coming out frequently. I would suggest bundling a specific version of node with Titanium build (which of course will be interesting since node requires a OS specific binary). Relying on my installed build of node would be a bad idea - i'm working with it occasionally and I don't neccesarily keep it up-to-date.
    * Hook support
    - this looks interesting for my use cases. would be a good extension/customization point.
    * rest of doc looks good. When will this be ready? :)

  6. May 15, 2012

    As I'm planning on using Ti CLI together with cloud9 (instead of VPN access), a courtesy version alignment with the cloud9 nodejs requirement would be appreciated.

  7. May 15, 2012

    What are the verbosity log levels? The spec mentions that debug is level 4, but that doesn't align with Node.JS log levels (there are no numbers) or POSIX syslog levels (debug is 7).

    1. May 15, 2012

      I also realized that there is an ambiguity. Does "-v 4" refer to debug level 4, or is the v taking the default and we are processing project at path ./4. I think that -v should not take any parameters, and we should introduce a separate --log-level flag or something equivalent to avoid this ambiguity.

  8. May 16, 2012

    I'd really love the drillbit CLI integration. I actually like drillbit.

    The CLI should prompt for required options that weren't provided on the command line. https://github.com/flatiron/prompt does this really well, and it's built into the flatiron framework. I used flatiron to create https://github.com/russfrank/tsm and I found that it really helped me get up and running quickly.  It also rolls in optimist, the best option parser of all time.  This stuff is all MIT.

    I think it looks great, I hope to see it on github soon so I can start hacking on it!

  9. May 18, 2012

    Thank you all for your feedback. At this time community RFC is closed and this spec will not be updated until a final version is released along with the CLI. We have no firm release commitment at this time, but will begin work within the next few weeks. This is a large task, and could take a significant amount of time (we have to keep working on the mainline Titanium Mobile project as well).

    Here are your most significant comments and questions, and how they will be addressed:

    1. node.js versioning: The initial release will be based off the current stable node.js release (0.6.18). There is no guarantee about timely version updates due to the amount of effort that will be required in vetting a node release. Our locked version will be distributed as part of Titanium Studio. For users with multiple node installs on their system, there will be a new optional CLI option, --node-version, which will specify an installed version of node to look for. Users can also use n manually if they have it installed. We want to keep the number of tools we install to a minimum.
    2. Package management: We will use npm, either by posting to the public repository or maintaining our own internal one, or possibly both.
    3. Dependencies: This can be handled by per-project pre/post hooks.
    4. Separation of "app" and "module": This should be unnecessary if we're using a require-based structure. For example we can have the titanium build command require/load different scripts based on platform and module (i.e. it could run a .js file titanium-build-ios-module). Project type detection can be done at the toplevel, and also not all commands are required to interoperate with both apps and modules (many user externals won't need to). There will be a published API (outside of the scope of this spec) for how commands which are loaded via require are:
      • Looked up
      • Called out to
    5. TIMOB-2371: This ticket will need to be addressed as part of the CLI implementation, and we'll need to get this information from Tony. This should have been included in the user stories/requirements. Results of these discussions may further affect the spec while in development.
    6. git and other integration: We will not provide this as builtins or even externals in the initial release. These tools can be user-provided, or developed in-house and distributed as externals via npm if required.
    7. Log levels: Logging/verbosity was written before the node.js requirement was delivered. These log levels will be changed to align with the current node.js (0.6.18) logging APIs.
    8. Prompt for required options: This is anathema to the common way CLIs (and UNIX tools in general) operate and could drastically interfere with CI servers. We will not offer this.
    1. May 21, 2012

      Tools with the best experience often do prompt for required options that weren't provided on the command line, such as jitsu (which, by the way, should be your reference for a well done CLI tool). It can't interfere with CI servers if all of the arguments are provided. I realize you're "closed for comments", but I wanted to make sure my position was clear.