hooks/README.md

   1 <!--
   2 #
   3 # Licensed to the Apache Software Foundation (ASF) under one
   4 # or more contributor license agreements.  See the NOTICE file
   5 # distributed with this work for additional information
   6 # regarding copyright ownership.  The ASF licenses this file
   7 # to you under the Apache License, Version 2.0 (the
   8 # "License"); you may not use this file except in compliance
   9 # with the License.  You may obtain a copy of the License at
  10 #
  11 # http://www.apache.org/licenses/LICENSE-2.0
  12 #
  13 # Unless required by applicable law or agreed to in writing,
  14 # software distributed under the License is distributed on an
  15 # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  16 #  KIND, either express or implied.  See the License for the
  17 # specific language governing permissions and limitations
  18 # under the License.
  19 #
  20 -->
  21 # Cordova Hooks
  22
  23 This directory may contain scripts used to customize cordova commands. This
  24 directory used to exist at `.cordova/hooks`, but has now been moved to the
  25 project root. Any scripts you add to these directories will be executed before
  26 and after the commands corresponding to the directory name. Useful for
  27 integrating your own build systems or integrating with version control systems.
  28
  29 __Remember__: Make your scripts executable.
  30
  31 ## Hook Directories
  32 The following subdirectories will be used for hooks:
  33
  34     after_build/
  35     after_compile/
  36     after_docs/
  37     after_emulate/
  38     after_platform_add/
  39     after_platform_rm/
  40     after_platform_ls/
  41     after_plugin_add/
  42     after_plugin_ls/
  43     after_plugin_rm/
  44     after_plugin_search/
  45     after_prepare/
  46     after_run/
  47     after_serve/
  48     before_build/
  49     before_compile/
  50     before_docs/
  51     before_emulate/
  52     before_platform_add/
  53     before_platform_rm/
  54     before_platform_ls/
  55     before_plugin_add/
  56     before_plugin_ls/
  57     before_plugin_rm/
  58     before_plugin_search/
  59     before_prepare/
  60     before_run/
  61     before_serve/
  62     pre_package/ <-- Windows 8 and Windows Phone only.
  63
  64 ## Script Interface
  65
  66 All scripts are run from the project's root directory and have the root directory passes as the first argument. All other options are passed to the script using environment variables:
  67
  68 * CORDOVA_VERSION - The version of the Cordova-CLI.
  69 * CORDOVA_PLATFORMS - Comma separated list of platforms that the command applies to (e.g.: android, ios).
  70 * CORDOVA_PLUGINS - Comma separated list of plugin IDs that the command applies to (e.g.: org.apache.cordova.file, org.apache.cordova.file-transfer)
  71 * CORDOVA_HOOK - Path to the hook that is being executed.
  72 * CORDOVA_CMDLINE - The exact command-line arguments passed to cordova (e.g.: cordova run ios --emulate)
  73
  74 If a script returns a non-zero exit code, then the parent cordova command will be aborted.
  75
  76 ## Writing hooks
  77
  78 We highly recommend writting your hooks using Node.js so that they are
  79 cross-platform. Some good examples are shown here:
  80
  81 [http://devgirl.org/2013/11/12/three-hooks-your-cordovaphonegap-project-needs/](http://devgirl.org/2013/11/12/three-hooks-your-cordovaphonegap-project-needs/)
  82
  83 Also, note that even if you are working on Windows, and in case your hook scripts aren't bat files (which is recommended, if you want your scripts to work in non-Windows operating systems) Cordova CLI will expect a shebang line as the first line for it to know the interpreter it needs to use to launch the script. The shebang line should match the following example:
  84
  85     #!/usr/bin/env [name_of_interpreter_executable]
  86