Migration From 1.x to 2.x

There are a few breaking changes in 2.x. This document will help you migrate your code from 1.x to 2.x.

Python Version Support

idf-build-apps 1.x supports Python 2.7 and Python 3.4 or newer. idf-build-apps 2.x only supports Python 3.7 or newer.

Normal Arguments to Keyword-only Arguments

In 2.x, we move some arguments from normal arguments to keyword-only arguments. This is to make the API more consistent and easier to use.

To understand the difference between these terms better, here’s a quick summary:

  • “positonal-only argument” means the argument is a positional-only argument. (python 3.8+ only)

  • “keyword-only argument” means the argument is a keyword-only argument.

  • “normal argument” means the argument is not a positional-only argument, nor a keyword-only argument.

For example, in the following function:

def foo(a, /, b, c, *, d=1, e=2, f=3):
    pass

  • “a” is a positional-only argument.

  • “b” and “c” are normal arguments.

  • “d”, “e”, and “f” are keyword-only arguments.

The following calls are valid:

foo(1, 2, 3, d=4, e=5, f=6)
foo(1, 2, c=3, d=4, e=5, f=6)
foo(1, b=2, c=3, d=4, e=5, f=6)

The following calls are invalid:

foo(1, 2, 3, 4, 5, 6)
foo(1, b=2, 3, d=4, e=5, f=6)
foo(a=1, b=2, c=3, d=4, e=5, f=6)

App.__init__()

The __init__ function of App class, and all its sub-classes, like CMakeApp, and MakeApp, now takes only app_dir, and target as normal arguments. All the rest of the arguments are keyword-only arguments.

Before:

app = App('foo', 'esp32', 'sdkconfig.ci', 'default')

After:

app = App('foo', 'esp32', sdkconfig_path='sdkconfig.ci', config_name='default')

or all in keyword-only arguments:

app = App(app_dir='foo', target='esp32', sdkconfig_path='sdkconfig.ci', config_name='default')

App.build()

The build function of App class, and all its sub-classes, like CMakeApp, and MakeApp, now takes all arguments as keyword-only arguments.

find_apps()

The find_apps function now takes only paths and target as normal arguments. All the rest of the arguments are keyword-only arguments.

build_apps()

The build_apps function now takes only apps as normal argument. All the rest of the arguments are keyword-only arguments.

Function Signature Changes

In 2.x, we change the signature of some functions to make them more intuitive and self-explanatory.

find_apps()

  • build_log_path is renamed to build_log_filename. The file will be generated under build_dir if specified.

  • size_json_path is renamed to size_json_filename. The file will be generated under build_dir if specified.

CLI Changes

In 2.x, we change the separator for some options to better differentiate them from None and empty list.

  • --modified-components

  • --modified-files

  • --ignore-app-dependencies-filepatterns

Before:

idf-build-apps build -p foo -t esp32 --modified-components foo bar --modified-files foo bar --ignore-app-dependencies-filepatterns foo bar

After:

idf-build-apps build -p foo -t esp32 --modified-components 'foo;bar' --modified-files 'foo;bar' --ignore-app-dependencies-filepatterns 'foo;bar'

passing '' to specify it as None

idf-build-apps build -p foo -t esp32 --modified-components ''

or passing ';' to specify it as an empty list

idf-build-apps build -p foo -t esp32 --modified-components ';'