How to Create a Minimal Application

Overview

This shows how to create a minimal project from an application template.

See Minimal Module/Library project for Modules or Libraries.

After following these instructions you will have a new python, C/C++ or Arduino project with support for most activities you'll need.

Applications

The new application project name is "test-123". Most of the steps below are for a python application since it is simplest.

initial

Create a directory for the project and set up minimal git

mkdir test-123
cd test-123

# must be a git project
git init

copy from template

Clone one of the templates:

Since this example is for python, clone devpy-app-template Copy files from the template. I use the "meld" diff tool, since it is very easy to copy files over and to see any differences.

# run meld in the background
meld ../devpy-app-template . &

Copy these files:

tools/install/do_install_ubu
tools/requirements.txt
tools/set_env.sh
.gitignore
.gitmodules
do_install
do_subm_update
doit
xplat.cfg

Update config files

Open the project in PyCharm or your preferred IDE.

Modify xplat.cfg: new name, description and other info:

is_module = False     << check: indicates an application
mod_tech = 'python'   << check: indicates python

mod_name = 'test-123'
doxy_desc = 'application to test 123'

# these are optional until you are ready to publish your app
author = 'Your Name'
email = 'your@email.com'
homepage_url = 'https://bitbucket.org/{mod_type}/{mod_name}/src/master'
download_url = 'https://bitbucket.org/{mod_type}/{mod_name}/get/master.zip'

setup xplat_utils

Set up the initial content for the xplat_utils submodule

./do_subm_update full

create python virtual environment

Modify tools/requirements.txt: add all modules you need

# example modules:
PyWavelets
numpy
matplotlib

Install the common modules and the ones your projects needs:

./do_install

in Pycharm: mark these directories as excluded:
- out
- venv
update Pycharm venv:
- Configure Python Interpreter
- Add New Interpreter
- Add Local Interpreter
- click Existing
- It should show the venv as the local interpreter
- click OK

create initial source file(s)

Add your script to the lib directory

mkdir doc   # needed by tools

mkdir lib
# create your script in lib
touch lib/test1.py

Update doit to invoke the script

# original: $pyexe lib/main.py "$@" | cmn_tee
$pyexe lib/test1.py "$@" | cmn_tee

run it

Typical output:

<snip>
==== doit: starting...
     gen: constants_version.py rc=0
hello world
     doit: run_it rc=0
<snip>

The lib directory should have a new file "constants_version.py". This contains the version string from xplat.cfg

The doc directory should have a new file "version_info.md". This contains which OS you've run this app on.

Ubuntu 22.04 jammy, Python 3.10

add additional modules if needed

If your script needs additional modules, add them to tools/requirements.txt and rerun do_install

./do_install
# rerun script to check it worked
./doit

other scripts available

The template has additional scripts you can use:

copy over do_check to double-check your setup is correct and to generate a License.txt file
copy over these to add Unit Tests
- do_ut
- pytest.ini
- setup.cfg
copy over these to add Verification tests
- do_ver
- pytest.ini
- setup.cfg
copy over these to add linter capabilities
- do_lint
- setup.cfg
copy over these to add the ability to generate doxygen documentation and PDF
- do_doc
- copy README_template.md and rename it to README.md
copy over do_clean to be able to clean up temp directories etc.

C/C++ Applications

initial

Create a directory for the project and set up minimal git

mkdir test-123
cd test-123

# must be a git project
git init

copy from template

Clone C/C++ devcpp-app-template

# run meld in the background
meld ../devcpp-app-template . &

Copy these files:

tools/install/do_install_ubu
tools/requirements.txt
tools/set_env.sh
.clang-format # include if you use source code formatting in CLion
.clang-tidy # include if you want CLion to report lint warnings
.gitignore
.gitmodules
do_build
do_gen
do_install
do_subm_update
doit
gen.py
xplat.cfg

Update config files

Open the project in CLion or your preferred IDE.

Modify xplat.cfg: new name, description and other info:

is_module = False    << check indicates an application
mod_tech = 'cpp'     << check indicates C/C++

mod_name = 'test-123'
doxy_desc = 'application to test 123'

# these are optional until you are ready to publish your app
author = 'Your Name'
email = 'your@email.com'
homepage_url = 'https://bitbucket.org/{mod_type}/{mod_name}/src/master'
download_url = 'https://bitbucket.org/{mod_type}/{mod_name}/get/master.zip'

setup xplat_utils

Set up the initial content for the xplat_utils submodule

./do_subm_update full

create python virtual environment

Note a Python venv is still needed because the tools are written in python

Note: tools/requirements.txt should be empty since the default modules are the ones needed ny the tools

Install the common modules:

./do_install

create initial source file(s)

mkdir doc   # needed by tools

mkdir src

touch src/main.cpp
# or main.c as needed

# include <cstdio>

// --------------------
auto main() -> int {
    printf("hello world\n");
}

generate Makefile

open gen.py
at this point, Clion will want to configure a venv:
- Configure Python Interpreter
- Add Interpreter
- Add Local Interpreter
- click Existing
- It should show the venv as the local interpreter
- click OK
create the Makefile targets
- temporarily comment out cpip target
- temporarily comment out gtest "ut" target

from pyalamake import alamake

# === C++ tgt
tgt = alamake.create('test-123', 'cpp')  << ensure target is test-123
tgt.add_sources([
    'src/main.cpp',
])
tgt.add_include_directories(['src'])

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

generate the Makefile

./do_gen

In CLion, open the Makefile.

There is a "Project is not configured" message.

Click on Fix....
Click "Load Makefile Project"
get dlgbox "Load Project"
ensure "Clean project" is selected
Click OK

build the app

./do_build

additional configuration

in CLion: mark these directories as excluded:
- out
- venv
- debug

run it

./doit

Typical output:

<snip>
---> do_makefile: starting target:test-123-run...
 --  1] debug/test-123
 --  2] hello world
OK   do_makefile: target test-123-run rc=0
<snip>

The src directory should have a new file "version.h". This contains the version string from xplat.cfg

The doc directory should have a new file "version_info.md". This contains which OS you've run this app on.

Ubuntu 22.04 jammy, Python 3.10

other scripts available

The template has additional scripts you can use:

copy over do_check to double-check your setup is correct and to generate a License.txt file
copy over these to add Unit Tests
- update gen.py for a gtest target and run ./do_gen to update Makefile
- do_ut
copy over these to add linter capabilities
- do_lint
- run ./do_lint for cppcheck or ./do_lint clang-tidy
copy over these to add the ability to generate doxygen documentation and PDF
- do_doc
- copy README_template.md and rename it to README.md
copy over do_clean to be able to clean up temp directories etc.

Arduino Applications

initial

Create a directory for the project and set up minimal git

mkdir test-123
cd test-123

# must be a git project
git init

copy from template

same as for C++ except:

Clone Arduino devino-app-template

# run meld in the background
meld ../devino-app-template . &

Copy these files:

tools/install/do_install_ubu
tools/requirements.txt
tools/set_env.sh
.clang-format # include if you use source code formatting in CLion
.clang-tidy # include if you want CLion to report lint warnings
.gitignore
.gitmodules
do_build
do_gen
do_install
do_subm_update
do_upload # uploads image to Arduino
doit
gen.py
xplat.cfg

Update config files

Open the project in CLion or your preferred IDE.

Modify xplat.cfg: new name, description and other info:

is_module = False        << check indicates an application
mod_tech = 'arduino'     << check indicates arduino

mod_name = 'test-123'
doxy_desc = 'application to test 123'

# these are optional until you are ready to publish your app
author = 'Your Name'
email = 'your@email.com'
homepage_url = 'https://bitbucket.org/{mod_type}/{mod_name}/src/master'
download_url = 'https://bitbucket.org/{mod_type}/{mod_name}/get/master.zip'

setup xplat_utils

Set up the initial content for the xplat_utils submodule

./do_subm_update full

create python virtual environment

Note a Python venv is still needed because the tools are written in python

Note: tools/requirements.txt should be empty since the default modules are the ones needed ny the tools

Install the common modules:

./do_install

create initial source file(s)

mkdir doc   # needed by tools

mkdir src

touch src/main.cpp
# or main.c as needed

same as for C++, except the source file has to be Arduino compatible.

//! Summary: Blink the arduino led using random count and delays between blinks
#include <Arduino.h>

//! holds mS between toggling the LED
unsigned long delaycount;
//! holds the number of blinks to do
unsigned long flashcount;

// --------------------
//! Arduino setup
void setup()
{
    // initialize the digital pin as an output.
    // Pin 13 has an LED connected on most Arduino boards:
    pinMode(13, OUTPUT);

    // delay between flashes: 0 to 255 ms
    delaycount = 120;
    // number of flashes: 0 - 15 times
    flashcount = 5;
}

// --------------------
//! Arduino main loop
// blink the LED rapidly for about a second
// turn it off for a full second
// and repeat
void loop()
{
    // set the pin high which turns on the LED and then wait a bit
    digitalWrite(13, HIGH);
    delay(delaycount);

    // do a turn on/turn off cycle N times
    // each cycle takes about 50 + 50 = 100ms
    for (unsigned long i = 0; i < flashcount; ++i) {
        // set the pin low which turns off the LED and then wait a bit
        digitalWrite(13, LOW);
        delay(delaycount);

        // turn on the LED and wait
        digitalWrite(13, HIGH);
        delay(delaycount);
    }

    // ensure the LED off
    digitalWrite(13, LOW);

    // wait for a second
    delay(1000);
}

generate Makefile

open gen.py
at this point, Clion will want to configure a venv:
- Configure Python Interpreter
- Add Interpreter
- Add Local Interpreter
- click Existing
- It should show the venv as the local interpreter
- If not, manually select venv/bin/python
- click OK
create the Makefile targets
- temporarily comment out gtest "ut" target
- needs an arduino core (see below)

from pyalamake import alamake

sh1 = alamake.create_arduino_shared()
sh1.set_boardid('nano-atmega328old')    # update to your board type
sh1.set_avrdude_port('/dev/ttyUSB0')    # update to the usb port for arduino programming

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

# === arduino tgt
tgt = alamake.create('test-123', 'arduino', shared=sh1)   << ensure target is test-123
tgt.add_sources([
    'src/main.cpp',
])
tgt.add_include_directories(['src'])

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

generate the Makefile

./do_gen

In CLion, open the Makefile.

There is a "Project is not configured" message.

Click on Fix....
Click "Load Makefile Project"
get dlgbox "Load Project"
ensure "Clean project" is selected
Click OK

build the app

./do_build

additional configuration

in CLion: mark these directories as excluded:
- out
- venv
- debug

run it

Turn on the Arduino; ensure it is plugged into the USB port.

./doit
# or since it is already built:
./do_upload

The output should indicate the arduino was flashed correctly.

The arduino LED should flash according to the values you used for

    delaycount = 120;
    flashcount = 5;

The src directory should have a new file "version.h". This contains the version string from xplat.cfg

The doc directory should have a new file "version_info.md". This contains which OS you've run this app on.

Ubuntu 22.04 jammy, Python 3.10

other scripts available

The template has additional scripts you can use:

copy over do_check to double-check your setup is correct and to generate a License.txt file
copy over these to add Unit Tests
- update gen.py for a gtest target and run ./do_gen to update Makefile
- do_ut
copy over these to add linter capabilities
- do_lint
- run ./do_lint for cppcheck or ./do_lint clang-tidy
copy over these to add the ability to generate doxygen documentation and PDF
- do_doc
- copy README_template.md and rename it to README.md
copy over do_clean to be able to clean up temp directories etc.