OVMS3-idf/tools/idf.py

#!/usr/bin/env python
#
# 'idf.py' is a top-level config/build command line tool for ESP-IDF
#
# You don't have to use idf.py, you can use cmake directly
# (or use cmake in an IDE)
#
#
#
# Copyright 2018 Espressif Systems (Shanghai) PTE LTD
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
import sys
import argparse
import os
import os.path
import subprocess
import multiprocessing
import re
import shutil
import json

# Use this Python interpreter for any subprocesses we launch
PYTHON=sys.executable

# note: os.environ changes don't automatically propagate to child processes,
# you have to pass this in explicitly
os.environ["PYTHON"]=sys.executable

# Make flavors, across the various kinds of Windows environments & POSIX...
if "MSYSTEM" in os.environ:  # MSYS
    MAKE_CMD = "make"
    MAKE_GENERATOR = "MSYS Makefiles"
elif os.name == 'nt':  # other Windows
    MAKE_CMD = "mingw32-make"
    MAKE_GENERATOR = "MinGW Makefiles"
else:
    MAKE_CMD = "make"
    MAKE_GENERATOR = "Unix Makefiles"

GENERATORS = [
    # ('generator name', 'build command line', 'version command line')
    ("Ninja", [ "ninja" ], [ "ninja", "--version" ]),
    (MAKE_GENERATOR, [ MAKE_CMD, "-j", str(multiprocessing.cpu_count()+2) ], [ "make", "--version" ]),
    ]
GENERATOR_CMDS = dict( (a[0], a[1]) for a in GENERATORS )

def check_environment():
    """
    Verify the environment contains the top-level tools we need to operate

    (cmake will check a lot of other things)
    """
    if not executable_exists(["cmake", "--version"]):
        raise RuntimeError("'cmake' must be available on the PATH to use idf.py")
    # find the directory idf.py is in, then the parent directory of this, and assume this is IDF_PATH
    detected_idf_path = os.path.realpath(os.path.join(os.path.dirname(__file__), ".."))
    if "IDF_PATH" in os.environ:
        set_idf_path = os.path.realpath(os.environ["IDF_PATH"])
        if set_idf_path != detected_idf_path:
            print("WARNING: IDF_PATH environment variable is set to %s but idf.py path indicates IDF directory %s. Using the environment variable directory, but results may be unexpected..."
                  % (set_idf_path, detected_idf_path))
    else:
        os.environ["IDF_PATH"] = detected_idf_path

def executable_exists(args):
    try:
        subprocess.check_output(args)
        return True
    except:
        return False

def detect_cmake_generator():
    """
    Find the default cmake generator, if none was specified. Raises an exception if no valid generator is found.
    """
    for (generator, _, version_check) in GENERATORS:
        if executable_exists(version_check):
            return generator
    raise RuntimeError("To use idf.py, either the 'ninja' or 'GNU make' build tool must be available in the PATH")

def _ensure_build_directory(args):
    """Check the build directory exists and that cmake has been run there.

    If this isn't the case, create the build directory (if necessary) and
    do an initial cmake run to configure it.

    This function will also check args.generator parameter. If the parameter is incompatible with
    the build directory, an error is raised. If the parameter is None, this function will set it to
    an auto-detected default generator or to the value already configured in the build directory.
    """
    project_dir = args.project_dir
    # Verify the project directory
    if not os.path.isdir(project_dir):
        if not os.path.exists(project_dir):
            raise RuntimeError("Project directory %s does not exist")
        else:
            raise RuntimeError("%s must be a project directory")
    if not os.path.exists(os.path.join(project_dir, "CMakeLists.txt")):
        raise RuntimeError("CMakeLists.txt not found in project directory %s" % project_dir)

    # Verify/create the build directory
    build_dir = args.build_dir
    if not os.path.isdir(build_dir):
        os.mkdir(build_dir)
    cache_path = os.path.join(build_dir, "CMakeCache.txt")
    if not os.path.exists(cache_path):
        if args.generator is None:
            args.generator = detect_cmake_generator()
        print("Running cmake...")
        # Note: we explicitly pass in os.environ here, as we may have set IDF_PATH there during startup
        try:
            subprocess.check_call(["cmake", "-G", args.generator, project_dir], env=os.environ, cwd=args.build_dir)
        except:
            if os.path.exists(cache_path):  # don't allow partial CMakeCache.txt files, to keep the "should I run cmake?" logic simple
                os.remove(cache_path)
            raise

    # Learn some things from the CMakeCache.txt file in the build directory
    cache = parse_cmakecache(cache_path)
    try:
        generator = cache["CMAKE_GENERATOR"]
    except KeyError:
        generator = detect_cmake_generator()
    if args.generator is None:
        args.generator = generator  # reuse the previously configured generator, if none was given
    if generator != args.generator:
        raise RuntimeError("Build is configured for generator '%s' not '%s'. Run 'idf.py fullclean' to start again."
                           % (generator, args.generator))

    try:
        home_dir = cache["CMAKE_HOME_DIRECTORY"]
        if os.path.realpath(home_dir) != os.path.realpath(project_dir):
            raise RuntimeError("Build directory '%s' configured for project '%s' not '%s'. Run 'idf.py fullclean' to start again."
                            % (build_dir, os.path.realpath(home_dir), os.path.realpath(project_dir)))
    except KeyError:
        pass  # if cmake failed part way, CMAKE_HOME_DIRECTORY may not be set yet


def parse_cmakecache(path):
    """
    Parse the CMakeCache file at 'path'.

    Returns a dict of name:value.

    CMakeCache entries also each have a "type", but this is currently ignored.
    """
    result = {}
    with open(path) as f:
        for line in f:
            # cmake cache lines look like: CMAKE_CXX_FLAGS_DEBUG:STRING=-g
            # groups are name, type, value
            m = re.match(r"^([^#/:=]+):([^:=]+)=(.+)\n$", line)
            if m:
               result[m.group(1)] = m.group(3)
    return result

def build_target(target_name, args):
    """
    Execute the target build system to build target 'target_name'

    Calls _ensure_build_directory() which will run cmake to generate a build
    directory (with the specified generator) as needed.
    """
    _ensure_build_directory(args)
    generator_cmd = GENERATOR_CMDS[args.generator]
    print("Running '%s %s' in %s..." % (generator_cmd, target_name, args.build_dir))
    subprocess.check_call(generator_cmd + [target_name], cwd=args.build_dir)

def _get_esptool_args(args):
    esptool_path = os.path.join(os.environ["IDF_PATH"], "components/esptool_py/esptool/esptool.py")
    result = [ PYTHON, esptool_path ]
    if args.port is not None:
        result += [ "-p", args.port ]
    result += [ "-b", str(args.baud) ]
    return result

def flash(action, args):
    """
    Run esptool to flash the entire project, from an argfile generated by the build system
    """
    flasher_args_path = {
        "bootloader-flash":      "flash_bootloader_args",
        "partition_table-flash": "flash_partition_table_args",
        "app-flash":             "flash_app_args",
        "flash":                 "flash_project_args",
    }[action]
    esptool_args = _get_esptool_args(args)
    esptool_args += [ "write_flash", "@"+flasher_args_path ]
    subprocess.check_call(esptool_args, cwd=args.build_dir)

def erase_flash(action, args):
    esptool_args = _get_esptool_args(args)
    esptool_args += [ "erase_flash" ]
    subprocess.check_call(esptool_args, cwd=args.build_dir)

def monitor(action, args):
    """
    Run idf_monitor.py to watch build output
    """
    desc_path = os.path.join(args.build_dir, "project_description.json")
    if not os.path.exists(desc_path):
        _ensure_build_directory(args)
    with open(desc_path, "r") as f:
        project_desc = json.load(f)

    elf_file = os.path.join(args.build_dir, project_desc["app_elf"])
    if not os.path.exists(elf_file):
        raise RuntimeError("ELF file '%s' not found. You need to build & flash the project before running 'monitor', and the binary on the device must match the one in the build directory exactly. Try 'idf.py flash monitor'." % elf_file)
    idf_monitor = os.path.join(os.environ["IDF_PATH"], "tools/idf_monitor.py")
    monitor_args = [PYTHON, idf_monitor ]
    if args.port is not None:
        monitor_args += [ "-p", args.port ]
    monitor_args += [ "-b", project_desc["monitor_baud"] ]
    monitor_args += [ elf_file ]
    subprocess.check_call(monitor_args, cwd=args.build_dir)

def clean(action, args):
    if not os.path.isdir(args.build_dir):
        print("Build directory '%s' not found. Nothing to clean." % args.build_dir)
        return
    build_target("clean", args)

def fullclean(action, args):
    build_dir = args.build_dir
    if not os.path.isdir(build_dir):
        print("Build directory '%s' not found. Nothing to clean." % build_dir)
        return
    if len(os.listdir(build_dir)) == 0:
        print("Build directory '%s' is empty. Nothing to clean." % build_dir)
        return

    if not os.path.exists(os.path.join(build_dir, "CMakeCache.txt")):
        raise RuntimeError("Directory '%s' doesn't seem to be a CMake build directory. Refusing to automatically delete files in this directory. Delete the directory manually to 'clean' it." % build_dir)
    red_flags = [ "CMakeLists.txt", ".git", ".svn" ]
    for red in red_flags:
        red = os.path.join(build_dir, red)
        if os.path.exists(red):
            raise RuntimeError("Refusing to automatically delete files in directory containing '%s'. Delete files manually if you're sure." % red)
    # OK, delete everything in the build directory...
    for f in os.listdir(build_dir):  # TODO: once we are Python 3 only, this can be os.scandir()
        f = os.path.join(build_dir, f)
        if os.path.isdir(f):
            shutil.rmtree(f)
        else:
            os.remove(f)

ACTIONS = {
    # action name : ( function (or alias), dependencies, order-only dependencies )
    "all" :                  ( build_target, [], [ "menuconfig", "clean", "fullclean" ] ),
    "build":                 ( "all",        [], [] ),  # build is same as 'all' target
    "clean":                 ( clean,        [], [ "fullclean" ] ),
    "fullclean":             ( fullclean,    [], [] ),
    "menuconfig":            ( build_target, [], [] ),
    "size":                  ( build_target, [], [ "app" ] ),
    "size-components":       ( build_target, [], [ "app" ] ),
    "size-files":            ( build_target, [], [ "app" ] ),
    "bootloader":            ( build_target, [], [] ),
    "bootloader-clean":      ( build_target, [], [] ),
    "bootloader-flash":      ( flash,        [ "bootloader" ], [] ),
    "app":                   ( build_target, [], [] ),
    "app-flash":             ( flash,        [], [ "app" ]),
    "partition_table":       ( build_target, [], [] ),
    "partition_table-flash": ( flash,        [ "partition_table" ], []),
    "flash":                 ( flash,        [ "all" ], [ ] ),
    "erase_flash":           ( erase_flash,  [], []),
    "monitor":               ( monitor,      [], [ "flash", "partition_table-flash", "bootloader-flash", "app-flash" ]),
}


def main():
    parser = argparse.ArgumentParser(description='ESP-IDF build management tool')
    parser.add_argument('-p', '--port', help="Serial port", default=None)
    parser.add_argument('-b', '--baud', help="Baud rate", default=460800)
    parser.add_argument('-C', '--project-dir', help="Project directory", default=os.getcwd())
    parser.add_argument('-B', '--build-dir', help="Build directory", default=None)
    parser.add_argument('-G', '--generator', help="Cmake generator", choices=GENERATOR_CMDS.keys())
    parser.add_argument('actions', help="Actions (build targets or other operations)", nargs='+',
                        choices=ACTIONS.keys())

    args = parser.parse_args()

    check_environment()

    # Advanced parameter checks
    if args.build_dir is not None and os.path.realpath(args.project_dir) == os.path.realpath(args.build_dir):
        raise RuntimeError("Setting the build directory to the project directory is not supported. Suggest dropping --build-dir option, the default is a 'build' subdirectory inside the project directory.")
    if args.build_dir is None:
        args.build_dir = os.path.join(args.project_dir, "build")
    args.build_dir = os.path.realpath(args.build_dir)

    completed_actions = set()
    def execute_action(action, remaining_actions):
        ( function, dependencies, order_dependencies ) = ACTIONS[action]
        # very simple dependency management, build a set of completed actions and make sure
        # all dependencies are in it
        for dep in dependencies:
            if not dep in completed_actions:
                execute_action(dep, remaining_actions)
        for dep in order_dependencies:
            if dep in remaining_actions and not dep in completed_actions:
                execute_action(dep, remaining_actions)

        if action in completed_actions:
            pass  # we've already done this, don't do it twice...
        elif function in ACTIONS:  # alias of another action
            execute_action(function, remaining_actions)
        else:
            function(action, args)

        completed_actions.add(action)

    while len(args.actions) > 0:
        execute_action(args.actions[0], args.actions[1:])
        args.actions.pop(0)


if __name__ == "__main__":
    main()