pyalamake


Namepyalamake JSON
Version 0.0.22 PyPI version JSON
download
home_pageNone
Summarypython module to generate Makefiles for arduino, GTest, /CC++, etc.
upload_time2024-12-08 03:11:40
maintainerNone
docs_urlNone
authorNone
requires_python>=3.9
licenseMIT
keywords makefile generation python
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            * website: <https://arrizza.com/pyalamake>
* installation: see <https://arrizza.com/setup-common>

## Summary

This Python module generates a multi-target Makefile for cross-platform projects all of which is compatible with
JetBrain's Clion IDE.

For example, see gen.py for a Python script (gen.py) that generates:

* two Arduino projects and an Arduino core for them
* a GTest project to run UTs against an Arduino Project
* a C/++ project

all into one Makefile, and all recognized by CLion.

See also gen_3cores.py that shows how to build 3 Arduino on 3 different boards in the same project and same Makefile.

## Why not CMake?

I use JetBrain's CLion. Ut can handle only a CMake or Makefile based project.

Also, I like to use GTest to UT my Arduino projects (if possible). But CMake can't handle a project that uses
two compilers i.e. avr-gcc for Arduino and gcc for GTest. It tried some different CMake techniques
to allow that but they either didn't work or CLion still didn't recognize the components being used.

The only option then was to use Python to generate a Makefile that CLion was compatible with.

## Why not ninja instead of make?

Because CLion can't use that to self-configure. CMake in CLion can be configured to use
Ninja, but the IDE uses CMake to configure itself for the project. Therefore, Makefile.

## Why?

Currently, I have relatively simple projects using one Arduino and some GTest UTs. But I do have some
projects that could use multiple Arduino's communicating with each other. And possibly some other
microcontrollers e.g. STM32, ESP32, etc. that communicate with Arduino's or themselves.

CLion can't handle that.

But (finger crossed) I should be able to extend pyalamake to build STM32 and ESP32 targets relatively easily, still
allow
GTests for those microcontrollers, etc.

## Limitations

* works only on Ubuntu. There will likely be additional work needed for macOS and Windows.
* Arduino libraries can not be added to a target.
* See todo.md for more work to be done.
* tested with an Arduino Nano (boardid: nano-atmega328old), Arduino MegaADK (boardid: megaadk) and Arduino Uno (boardid:
  uno).
  Other boards should work correctly, but there is always a possibility it fails.
* I have not tested using an Arduino programmer
* I have not tested an app that requires Arduino EEPROM uploads.

## How to use

```bash
./gen.py    # to generate/update the Makefile

make help   # to show the list of makefile targets

make                # build all targets: Arduino core, both blink targets, GTest UT, and sample C++ app

make blink-upload   # upload the blink app to an Arduino; 
                    # should blink random times (2 - 15) and random rate (0 - 255ms);
make blink2-upload  # upload the blink2 app to an Arduino;
                    # should blink 2 times
make core           # build the Arduino Core

make ut-run         # run the GTEST unit tests
make ut-cov         # show the source code coverage of the GTEST UTs
                    # open debug/ut.html in a browser for a gcov HTML report
make ut-cov-reset   # reset the coverage data

make hello-run            # run C++ hello world app
make hello-run s="john"   # to pass a CLI args to hello world 

make clean         # clean all
make <tgt>-clean   # clean a specific target
```

## updating gen.py

```python
from pyalamake.lib.pyalamake import alamake

# specify all components to be added to the makefile
# ... skip see below ...

# === generate makefile for all targets
alamake.makefile()

```

At this point, the Makefile should contain all targets specified

#### Arduino targets

Creating an Arduino .hex requires 3 steps:

1) gen an Arduino Shared component
    * holds common, shared information like boardid, serial port, etc.
2) gen an Arduino Core
    * use the same shared component created above
    * holds the Arduino Core library compiled for the same boardid, etc.
3) gen the Arduino App
    * use the same shared component created above
    * holds the Arduino app compiled for the same boardid etc.

A shared component and core can be used with multiple Arduino targets.

Example generation of an Arduino shared component:

```python
sh1 = alamake.create_arduino_shared()
sh1.set_boardid('nano-atmega328old')
# sh1.set_boardid('uno')
# sh1.set_boardid('megaadk')

# on Ubuntu, different boards use different serial ports 
if sh1.boardid in ['uno', 'megaadk']:
    sh1.set_avrdude_port('/dev/ttyACM0')
else:
    sh1.set_avrdude_port('/dev/ttyUSB0')

# at this point sh1 is only missing core related settings
```

Example generation of an Arduino core:

```python
# share the same component created above
core = alamake.create('core', 'arduino-core', shared=sh1)
# no additional directories, libs, etc. needed
core.check()
```

Example generation of an Arduino target:

```python
# share the same component created above
blink = alamake.create('blink', 'arduino', shared=sh1)
blink.add_sources([
    'src1/blink.cpp',
    'src1/common.cpp',
])
blink.add_include_directories(['src'])
```

#### GTest target

Example generation of a GTest target that tests an Arduino app

```python
ut = alamake.create('ut', 'gtest')

# tests the blink2.cpp (Arduino) in src2 directory
ut.add_include_directories([
    'src2',
    'ut/mock_arduino',
])

# uses a Mock Arduino library to check blink2 behavior
ut.add_sources([
    'ut/mock_arduino/mock_arduino.cpp',
    'ut/ut_test1.cpp',
])

# specify the directory(s) that should be part of the coverage report
ut.add_coverage(['src2'])

```

#### C++ targets

Example generation of a C++ target

```python
hello = alamake.create('hello', 'cpp')
hello.add_include_directories(['src'])
hello.add_sources([
    'src1/hello.cpp',
])
```

## Convert Arduino from cmake

Convert:

```cmake
cmake_minimum_required(VERSION 3.16)
set(CMAKE_TOOLCHAIN_FILE ${CMAKE_SOURCE_DIR}/arduino-cmake/ArduinoToolchain.cmake)

project(blink)
print_board_list()
# set to your board
set(MY_BOARD nano328p)
set(MY_PORT /dev/ttyUSB0)
```

to:

```python
# === create a shared component for core and arduino project
sh1 = alamake.create_arduino_shared()
sh1.set_boardid('nano-atmega328old')
sh1.set_avrdude_port('/dev/ttyUSB0')
# at this point sh1 is only missing core related settings

# === arduino core
core = alamake.create('core', 'arduino-core', shared=sh1)
# no additional directories, libs, etc. needed
core.check()

# === arduino blink
blink = alamake.create('blink', 'arduino', shared=sh1)
```

Convert:

```cmake
generate_arduino_firmware(${CMAKE_PROJECT_NAME}
        # NOTE: these are converted above
        BOARD ${MY_BOARD}
        PORT ${MY_PORT}   # note: required otherwise will not generate upload target

        SRCS src/main.cpp
)
```

to:

```python

blink = alamake.create('blink', 'arduino', shared=sh1)
blink.add_sources([
    'src1/main.cpp',
])
blink.add_include_directories(['src'])
```

## Convert gtest

TODO

## Convert C++

TODO

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "pyalamake",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": "\"J. Arrizza\" <cppgent0@gmail.com>",
    "keywords": "makefile, generation, python",
    "author": null,
    "author_email": "\"J. Arrizza\" <cppgent0@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/cb/88/9f5784ce1a156d4b7660117aa82c113df63f0bd6e02d4e47da6d1f9441ec/pyalamake-0.0.22.tar.gz",
    "platform": null,
    "description": "* website: <https://arrizza.com/pyalamake>\n* installation: see <https://arrizza.com/setup-common>\n\n## Summary\n\nThis Python module generates a multi-target Makefile for cross-platform projects all of which is compatible with\nJetBrain's Clion IDE.\n\nFor example, see gen.py for a Python script (gen.py) that generates:\n\n* two Arduino projects and an Arduino core for them\n* a GTest project to run UTs against an Arduino Project\n* a C/++ project\n\nall into one Makefile, and all recognized by CLion.\n\nSee also gen_3cores.py that shows how to build 3 Arduino on 3 different boards in the same project and same Makefile.\n\n## Why not CMake?\n\nI use JetBrain's CLion. Ut can handle only a CMake or Makefile based project.\n\nAlso, I like to use GTest to UT my Arduino projects (if possible). But CMake can't handle a project that uses\ntwo compilers i.e. avr-gcc for Arduino and gcc for GTest. It tried some different CMake techniques\nto allow that but they either didn't work or CLion still didn't recognize the components being used.\n\nThe only option then was to use Python to generate a Makefile that CLion was compatible with.\n\n## Why not ninja instead of make?\n\nBecause CLion can't use that to self-configure. CMake in CLion can be configured to use\nNinja, but the IDE uses CMake to configure itself for the project. Therefore, Makefile.\n\n## Why?\n\nCurrently, I have relatively simple projects using one Arduino and some GTest UTs. But I do have some\nprojects that could use multiple Arduino's communicating with each other. And possibly some other\nmicrocontrollers e.g. STM32, ESP32, etc. that communicate with Arduino's or themselves.\n\nCLion can't handle that.\n\nBut (finger crossed) I should be able to extend pyalamake to build STM32 and ESP32 targets relatively easily, still\nallow\nGTests for those microcontrollers, etc.\n\n## Limitations\n\n* works only on Ubuntu. There will likely be additional work needed for macOS and Windows.\n* Arduino libraries can not be added to a target.\n* See todo.md for more work to be done.\n* tested with an Arduino Nano (boardid: nano-atmega328old), Arduino MegaADK (boardid: megaadk) and Arduino Uno (boardid:\n  uno).\n  Other boards should work correctly, but there is always a possibility it fails.\n* I have not tested using an Arduino programmer\n* I have not tested an app that requires Arduino EEPROM uploads.\n\n## How to use\n\n```bash\n./gen.py    # to generate/update the Makefile\n\nmake help   # to show the list of makefile targets\n\nmake                # build all targets: Arduino core, both blink targets, GTest UT, and sample C++ app\n\nmake blink-upload   # upload the blink app to an Arduino; \n                    # should blink random times (2 - 15) and random rate (0 - 255ms);\nmake blink2-upload  # upload the blink2 app to an Arduino;\n                    # should blink 2 times\nmake core           # build the Arduino Core\n\nmake ut-run         # run the GTEST unit tests\nmake ut-cov         # show the source code coverage of the GTEST UTs\n                    # open debug/ut.html in a browser for a gcov HTML report\nmake ut-cov-reset   # reset the coverage data\n\nmake hello-run            # run C++ hello world app\nmake hello-run s=\"john\"   # to pass a CLI args to hello world \n\nmake clean         # clean all\nmake <tgt>-clean   # clean a specific target\n```\n\n## updating gen.py\n\n```python\nfrom pyalamake.lib.pyalamake import alamake\n\n# specify all components to be added to the makefile\n# ... skip see below ...\n\n# === generate makefile for all targets\nalamake.makefile()\n\n```\n\nAt this point, the Makefile should contain all targets specified\n\n#### Arduino targets\n\nCreating an Arduino .hex requires 3 steps:\n\n1) gen an Arduino Shared component\n    * holds common, shared information like boardid, serial port, etc.\n2) gen an Arduino Core\n    * use the same shared component created above\n    * holds the Arduino Core library compiled for the same boardid, etc.\n3) gen the Arduino App\n    * use the same shared component created above\n    * holds the Arduino app compiled for the same boardid etc.\n\nA shared component and core can be used with multiple Arduino targets.\n\nExample generation of an Arduino shared component:\n\n```python\nsh1 = alamake.create_arduino_shared()\nsh1.set_boardid('nano-atmega328old')\n# sh1.set_boardid('uno')\n# sh1.set_boardid('megaadk')\n\n# on Ubuntu, different boards use different serial ports \nif sh1.boardid in ['uno', 'megaadk']:\n    sh1.set_avrdude_port('/dev/ttyACM0')\nelse:\n    sh1.set_avrdude_port('/dev/ttyUSB0')\n\n# at this point sh1 is only missing core related settings\n```\n\nExample generation of an Arduino core:\n\n```python\n# share the same component created above\ncore = alamake.create('core', 'arduino-core', shared=sh1)\n# no additional directories, libs, etc. needed\ncore.check()\n```\n\nExample generation of an Arduino target:\n\n```python\n# share the same component created above\nblink = alamake.create('blink', 'arduino', shared=sh1)\nblink.add_sources([\n    'src1/blink.cpp',\n    'src1/common.cpp',\n])\nblink.add_include_directories(['src'])\n```\n\n#### GTest target\n\nExample generation of a GTest target that tests an Arduino app\n\n```python\nut = alamake.create('ut', 'gtest')\n\n# tests the blink2.cpp (Arduino) in src2 directory\nut.add_include_directories([\n    'src2',\n    'ut/mock_arduino',\n])\n\n# uses a Mock Arduino library to check blink2 behavior\nut.add_sources([\n    'ut/mock_arduino/mock_arduino.cpp',\n    'ut/ut_test1.cpp',\n])\n\n# specify the directory(s) that should be part of the coverage report\nut.add_coverage(['src2'])\n\n```\n\n#### C++ targets\n\nExample generation of a C++ target\n\n```python\nhello = alamake.create('hello', 'cpp')\nhello.add_include_directories(['src'])\nhello.add_sources([\n    'src1/hello.cpp',\n])\n```\n\n## Convert Arduino from cmake\n\nConvert:\n\n```cmake\ncmake_minimum_required(VERSION 3.16)\nset(CMAKE_TOOLCHAIN_FILE ${CMAKE_SOURCE_DIR}/arduino-cmake/ArduinoToolchain.cmake)\n\nproject(blink)\nprint_board_list()\n# set to your board\nset(MY_BOARD nano328p)\nset(MY_PORT /dev/ttyUSB0)\n```\n\nto:\n\n```python\n# === create a shared component for core and arduino project\nsh1 = alamake.create_arduino_shared()\nsh1.set_boardid('nano-atmega328old')\nsh1.set_avrdude_port('/dev/ttyUSB0')\n# at this point sh1 is only missing core related settings\n\n# === arduino core\ncore = alamake.create('core', 'arduino-core', shared=sh1)\n# no additional directories, libs, etc. needed\ncore.check()\n\n# === arduino blink\nblink = alamake.create('blink', 'arduino', shared=sh1)\n```\n\nConvert:\n\n```cmake\ngenerate_arduino_firmware(${CMAKE_PROJECT_NAME}\n        # NOTE: these are converted above\n        BOARD ${MY_BOARD}\n        PORT ${MY_PORT}   # note: required otherwise will not generate upload target\n\n        SRCS src/main.cpp\n)\n```\n\nto:\n\n```python\n\nblink = alamake.create('blink', 'arduino', shared=sh1)\nblink.add_sources([\n    'src1/main.cpp',\n])\nblink.add_include_directories(['src'])\n```\n\n## Convert gtest\n\nTODO\n\n## Convert C++\n\nTODO\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "python module to generate Makefiles for arduino, GTest, /CC++, etc.",
    "version": "0.0.22",
    "project_urls": {
        "Download": "https://bitbucket.org/arrizza-public/pyalamake/get/master.zip",
        "Source": "https://bitbucket.org/arrizza-public/pyalamake/src/master",
        "Website": "https://arrizza.com/pyalamake"
    },
    "split_keywords": [
        "makefile",
        " generation",
        " python"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "cb889f5784ce1a156d4b7660117aa82c113df63f0bd6e02d4e47da6d1f9441ec",
                "md5": "52f7c97e32a708a1e94663806ef3b674",
                "sha256": "dd903161fade57325b68a1f2358423c0970982c3b36e71d84d965f4a60c50c04"
            },
            "downloads": -1,
            "filename": "pyalamake-0.0.22.tar.gz",
            "has_sig": false,
            "md5_digest": "52f7c97e32a708a1e94663806ef3b674",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 24841,
            "upload_time": "2024-12-08T03:11:40",
            "upload_time_iso_8601": "2024-12-08T03:11:40.673960Z",
            "url": "https://files.pythonhosted.org/packages/cb/88/9f5784ce1a156d4b7660117aa82c113df63f0bd6e02d4e47da6d1f9441ec/pyalamake-0.0.22.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-12-08 03:11:40",
    "github": false,
    "gitlab": false,
    "bitbucket": true,
    "codeberg": false,
    "bitbucket_user": "arrizza-public",
    "bitbucket_project": "pyalamake",
    "lcname": "pyalamake"
}
        
Elapsed time: 0.45241s