bulgogi 0.0.9.dev5

A flexible build system assistant.

bulgogi-py

The Python interface for bulgogi.

Motive

1. Rather than write a CLI from scratch, using a scripting language as the interface seemed cool and appropriate for this project.
2. Build configurations are slow-changing and repititious, making scripts ideal for the job.

Installation

To get started, install bulgogi using pip:

pip install bulgogi 

Once installed at the user-level, use it in your latest build project.

Building from scratch

If your development platform is unlucky enough to be missing a compatible pre-built wheel distribution, the following instructions can be used to build the Python package from source.

Build dependencies

The following system dependencies are required:

• git
• gcc
• make
• libtool
• python3
  • pip
  • build
• python3-devel

Build instructions

Once system dependencies are installed, install the package from the upstream git repository:

pip install git+https://github.com/High-Intensity-Prototyping-Labs/bulgogi-py.git 

This should run and execute the build sequence required and install the system locally.

Build troubleshooting

If errors are encountered during build, an attempt at a manual build would be best for debugging purposes.

Clone the bulgogi-py repository and run the build.sh script on a UNIX-like system:

git clone https://github.com/High-Intensity-Prototyping-Labs/bulgogi-py.git 

cd bulgogi-py 

./build.sh 

With a careful eye and enough experience, the verbose build output should yield useful information to troubleshoot issues.

Usage

1. Create setup.py

First create the setup.py file in the root of your build project and declare your project:

# setup.py 
import bulgogi as bul 

bul.new_project('My Project')
bul.set_version('v1.0.0')

...

2. Declare targets

The next step is to declare targets based on your project layout:

...

target1 = bul.add_target('target1', bul.LIB)
execute = bul.add_target('execute', bul.EXE)

...

3. Declare relations

Targets need to be linked in some kind of way. This is usually referred to as 'dependency linking'.

In the Python interface for bulgogi, dependencies are linked by target ID:

...

bul.add_target_dep(execute, target1)

...

4. Commit the setup

Lastly, the build configuration must be commit to disk before it can be built:

...

bul.commit()

Putting it all together

# setup.py 
import bulgogi as bul 

bul.new_project('My Project')
bul.set_version('v1.0.0')

target1 = bul.add_target('target1', bul.LIB)
execute = bul.add_target('execute', bul.EXE)

bul.add_target_dep(execute, target1)

bul.commit()

This will generate a project.yaml file in the root of your directory and resemble something like:

execute:
  - target1

Usually configuration files are guarded from manual edits - but bulgogi in fact encourages the developer to modify the project.yaml file as they please.

Where are all the sources?

Although targets have been declared and dependencies linked, the best bulgogi can do to find the source files to copmile is to guess.

As a sane default, it will guess that each target has a directory matching its name (target1/ and execute/ in this case) and look for src and inc directories within.

This means - yes - that in theory the setup.py script can be ommitted altogether. This is not defeatist - it's to highlight that the script is most useful to standardize project configuration for all bulgogi targets, even if the project isn't your own.

Declaring sources

In the setup.py, target sources can be declared:

...

bul.add_sources(target1, 'target1/src/*.c')
bul.add_headers(target1, 'target1/inc/*.h')

...

bul.commit()

This can be done anytime after target1 has been added but before the configuration is committed to disk.

Patterns

It is evident that a specific files were not specified for the target sources. Patterns such as *.c are used instead and are known as 'globbing'.

Globbing

Globbing is a mixed subject among build system afficionados. Bulgogi offers it as a built-in feature and allows users to decide how they would like to approach.

...

# Adding individual files is allowed.
bul.add_sources(target1, 'target1/src/hello.c')
bul.add_sources(target1, 'target1/src/dog.c')
bul.add_sources(target1, 'target1/src/cat.c')

...

# Files can be 'globbed' by file-extension.
bul.add_sources(target1, 'target1/src/*.c')
bul.add_sources(target1, 'target1/src/*.cpp')

...

# Globbing can also be performed recursively.
bul.add_headers(target1, 'target1/inc/**.c')


bul.commit()

Variables

A benefit of using a feature-complete scripting language is the built-in availability of variables.

...

targets = ['target1', 'execute']
src_dir = 'src'
inc_dir = 'inc'

for target in targets:
    bul.add_sources(target, bul.names(target) + '/' + SRC_DIR + '/*.c')
    bul.add_headers(target, bul.names(target) + '/' + INC_DIR + '/*.h')

bul.commit()

License

bulgogi-py by Alex Amellal is licensed under CC BY 4.0