# 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.

## Logging Related Changes

In 2.x, we're following the standard Python logging convention.

Before:

```python
from idf_build_apps import LOGGER
```

After:

```python
import logging
idf_build_apps_logger = logging.getLogger('idf_build_apps')
```

## 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:

```python
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:

```python
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:

```python
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:

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

After:

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

or all in keyword-only arguments:

```python
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:

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

After:

```shell
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`

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

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

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