Pilot Light Build

These details have not been verified by PyPI

Project links

Homepage

Project description

Pilot Light Build

The pl-build tool is a lightweight utility used to generate batch/bash build scripts.

Background

The pl-build tool is a part of the larger Pilot Light project. In this larger project, we do not have a "build system" per se. Instead we prefer to write batch/bash scripts that directly call the compiler (in a manner similar to Casey Muratori's Handmade Hero). If this project was an end user product, this would be the end of it. However, this is not the case. It is meant to be easily extended through adding additional extensions and being used as a "pilot light" to start new projects. With this comes a couple issues. Extensions are meant to be cross platform so users need the ability to easily add new binaries for all target platforms with minimal duplication. Users shouldn't need to be bash or batch scripting experts to build new targets for all platforms and shouldn't need to test the build scripts continuously on each platform.

Another way of putting it, is we want to focus on what matters to build binaries. Ultimately this is just compiler & linker settings. We don't want to think about the differences in bash/batch syntax.

The idea is simple:

flowchart LR

    gen_build.py --> build_win32.bat

    gen_build.py --> build_linux.sh

    gen_build.py --> build_macos.sh

Features

entire system can be understood in an hour
minimizes duplicated information
generates standalone simple build scripts
fine-grained control over compilation & linker settings
supports hot reloading
easily extended to add new platforms & compilers
extremely light weight
no preference on editor/IDE
doesn't pretend different platforms don't exist

Documentation

Documentation can be found here.

Examples

Real World

Complete & more advanced examples can be found here:

Basic Example

This is just an example of the what an input and output scripts look like (this will not actually run).

input - gen_build.py

import pl_build.core as pl

import pl_build.backend_win32 as win32

import pl_build.backend_linux as linux

import pl_build.backend_macos as macos



with pl.project("tutorial"):



    pl.set_hot_reload_target("../out/pilot_light")



    with pl.target("example", pl.TargetType.EXECUTABLE):



        # shared across configs

        pl.set_output_directory("out")

        pl.set_output_binary("example")

        pl.add_source_files("main.c")



        with pl.configuration("debug"):



            with pl.platform("Windows"):

                with pl.compiler("msvc"):

                    pl.add_compiler_flags("-Od")



            with pl.platform("Linux"):

                with pl.compiler("gcc"):

                    pl.add_compiler_flags("-g")

                    pl.add_linker_flags("-ldl")



            with pl.platform("Darwin"):

                with pl.compiler("clang"):

                    pl.add_compiler_flags("-g", "--debug")

                    pl.add_linker_flags("-Wl,-rpath,/usr/local/lib")

                    

win32.generate_build("build_win32.bat")

linux.generate_build("build_linux.sh")

macos.generate_build("build_macos.sh")

output - build_win32.bat

:: Project: tutorial

:: Auto Generated by:

:: "pl_build.py" version: 1.0.5



:: Project: tutorial



:: ################################################################################

:: #                              Development Setup                               #

:: ################################################################################



:: keep environment variables modifications local

@setlocal



:: make script directory CWD

@pushd %~dp0

@set dir=%~dp0



:: default compilation result

@set PL_RESULT=[1m[92mSuccessful.[0m



:: default configuration

@set PL_CONFIG=debug



:: check command line args for configuration

:CheckConfiguration

@if "%~1"=="-c" (@set PL_CONFIG=%2) & @shift & @shift & @goto CheckConfiguration

@if "%PL_CONFIG%" equ "debug" ( goto debug )



:: ################################################################################

:: #                            configuration | debug                             #

:: ################################################################################



:debug



:: create output directories

@if not exist "out" @mkdir "out"



:: create lock file(s)

@echo LOCKING > "out/lock.tmp"



@if exist "out/tutorial.exe" del "out\tutorial.exe"

@if exist "out/tutorial_*.pdb" del "out\tutorial_*.pdb"



::~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ tutorial | debug ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



@set PL_LINKER_FLAGS=-incremental:no 

@set PL_SOURCES="main.c" 



:: run compiler (and linker)

@echo.

@echo [1m[93mStep: tutorial[0m

@echo [1m[93m~~~~~~~~~~~~~~~~~~~~~~[0m

@echo [1m[36mCompiling and Linking...[0m



:: call compiler

cl %PL_SOURCES% -Fe"out/tutorial.exe" -Fo"out/" -link %PL_LINKER_FLAGS% -PDB:"out/tutorial_%random%.pdb"



:: check build status

@set PL_BUILD_STATUS=%ERRORLEVEL%



:: failed

@if %PL_BUILD_STATUS% NEQ 0 (

    @echo [1m[91mCompilation Failed with error code[0m: %PL_BUILD_STATUS%

    @set PL_RESULT=[1m[91mFailed.[0m

    goto Cleanupdebug

)



:: print results

@echo [36mResult: [0m %PL_RESULT%

@echo [36m~~~~~~~~~~~~~~~~~~~~~~[0m



:Exit_tutorial



:Cleanupdebug



@echo [1m[36mCleaning...[0m



:: delete obj files(s)

@del "out\*.obj"  > nul 2> nul



:: delete lock file(s)

@if exist "out/lock.tmp" del "out\lock.tmp"



:: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:: end of debug configuration

goto ExitLabel



:ExitLabel



:: return CWD to previous CWD

@popd

output - build_macos.sh

# Auto Generated by:

# "pl_build.py" version: 1.0.5



# Project: tutorial



# ################################################################################

# #                              Development Setup                               #

# ################################################################################



# colors

BOLD=$'\e[0;1m'

RED=$'\e[0;31m'

RED_BG=$'\e[0;41m'

GREEN=$'\e[0;32m'

GREEN_BG=$'\e[0;42m'

CYAN=$'\e[0;36m'

MAGENTA=$'\e[0;35m'

YELLOW=$'\e[0;33m'

WHITE=$'\e[0;97m'

NC=$'\e[0m'



# find directory of this script

SOURCE=${BASH_SOURCE[0]}

while [ -h "$SOURCE" ]; do # resolve $SOURCE until the file is no longer a symlink

  DIR=$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )

  SOURCE=$(readlink "$SOURCE")

  [[ $SOURCE != /* ]] && SOURCE=$DIR/$SOURCE # if $SOURCE was a relative symlink, we need to resolve it relative to the path where the symlink file was located

done

DIR=$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )



# get architecture (intel or apple silicon)

ARCH="$(uname -m)"



# make script directory CWD

pushd $DIR >/dev/null



# default configuration

PL_CONFIG=debug



# check command line args for configuration

while getopts ":c:" option; do

   case $option in

   c) # set conf

         PL_CONFIG=$OPTARG;;

     \?) # Invalid option

         echo "Error: Invalid option"

         exit;;

   esac

done



# ################################################################################

# #                            configuration | debug                             #

# ################################################################################



if [[ "$PL_CONFIG" == "debug" ]]; then



# create output directory(s)

mkdir -p "out"



# create lock file(s)

echo LOCKING > "out/lock.tmp"



# check if this is a reload

PL_HOT_RELOAD_STATUS=0



# # let user know if hot reloading

running_count=$(ps aux | grep -v grep | grep -ci "pilot_light")

if [ $running_count -gt 0 ]

then

    PL_HOT_RELOAD_STATUS=1

    echo

    echo echo ${BOLD}${WHITE}${RED_BG}--------${GREEN_BG} HOT RELOADING ${RED_BG}--------${NC}

    echo echo

else

    # cleanup binaries if not hot reloading

    echo PL_HOT_RELOAD_STATUS=0

    rm -f "out/tutorial"



fi

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ tutorial | debug ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



# skip during hot reload

if [ $PL_HOT_RELOAD_STATUS -ne 1 ]; then



PL_RESULT=${BOLD}${GREEN}Successful.${NC}

PL_DEFINES=""

PL_INCLUDE_DIRECTORIES=""

PL_LINK_DIRECTORIES=""

PL_COMPILER_FLAGS="-g --debug "

PL_LINKER_FLAGS="-Wl,-rpath,/usr/local/lib "

PL_STATIC_LINK_LIBRARIES=""

PL_DYNAMIC_LINK_LIBRARIES=""

PL_SOURCES="main.c "

PL_LINK_FRAMEWORKS=""



# add flags for specific hardware

if [[ "$ARCH" == "arm64" ]]; then

    PL_COMPILER_FLAGS+="-arch arm64 "

else

    PL_COMPILER_FLAGS+="-arch x86_64 "

fi



# run compiler (and linker)

echo

echo ${YELLOW}Step: tutorial${NC}

echo ${YELLOW}~~~~~~~~~~~~~~~~~~~${NC}

echo ${CYAN}Compiling and Linking...${NC}

clang $PL_SOURCES $PL_INCLUDE_DIRECTORIES $PL_DEFINES $PL_COMPILER_FLAGS $PL_INCLUDE_DIRECTORIES $PL_LINK_DIRECTORIES $PL_LINKER_FLAGS $PL_STATIC_LINK_LIBRARIES $PL_DYNAMIC_LINK_LIBRARIES -o "./out/tutorial"



# check build status

if [ $? -ne 0 ]

then

    PL_RESULT=${BOLD}${RED}Failed.${NC}

fi



# print results

echo ${CYAN}Results: ${NC} ${PL_RESULT}

echo ${CYAN}~~~~~~~~~~~~~~~~~~~~~~${NC}



# hot reload skip

fi



# delete lock file(s)

rm -f "out/lock.tmp"



# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

# end of debug

fi





# return CWD to previous CWD

popd >/dev/null

output - build_linux.sh

#!/bin/bash



# Auto Generated by:

# "pl_build.py" version: 1.0.5



# Project: tutorial



# ################################################################################

# #                              Development Setup                               #

# ################################################################################



# colors

BOLD=$'\e[0;1m'

RED=$'\e[0;31m'

RED_BG=$'\e[0;41m'

GREEN=$'\e[0;32m'

GREEN_BG=$'\e[0;42m'

CYAN=$'\e[0;36m'

MAGENTA=$'\e[0;35m'

YELLOW=$'\e[0;33m'

WHITE=$'\e[0;97m'

NC=$'\e[0m'



# find directory of this script

SOURCE=${BASH_SOURCE[0]}

while [ -h "$SOURCE" ]; do # resolve $SOURCE until the file is no longer a symlink

  DIR=$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )

  SOURCE=$(readlink "$SOURCE")

  [[ $SOURCE != /* ]] && SOURCE=$DIR/$SOURCE # if $SOURCE was a relative symlink, we need to resolve it relative to the path where the symlink file was located

done

DIR=$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )



# make script directory CWD

pushd $DIR >/dev/null



# default configuration

PL_CONFIG=debug



# check command line args for configuration

while getopts ":c:" option; do

   case $option in

   c) # set conf

         PL_CONFIG=$OPTARG;;

     \?) # Invalid option

         echo "Error: Invalid option"

         exit;;

   esac

done



# ################################################################################

# #                            configuration | debug                             #

# ################################################################################



if [[ "$PL_CONFIG" == "debug" ]]; then



# create output directory(s)

mkdir -p "out"



# create lock file(s)

echo LOCKING > "out/lock.tmp"



# check if this is a reload

PL_HOT_RELOAD_STATUS=0



# # let user know if hot reloading

if pidof -x "pilot_light" -o $$ >/dev/null;then

    PL_HOT_RELOAD_STATUS=1

    echo

    echo echo ${BOLD}${WHITE}${RED_BG}--------${GREEN_BG} HOT RELOADING ${RED_BG}--------${NC}

    echo echo

else

    # cleanup binaries if not hot reloading

    echo PL_HOT_RELOAD_STATUS=0

    rm -f "out/tutorial"





fi

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ tutorial | debug ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



# skip during hot reload

if [ $PL_HOT_RELOAD_STATUS -ne 1 ]; then



PL_RESULT=${BOLD}${GREEN}Successful.${NC}

PL_DEFINES=""

PL_INCLUDE_DIRECTORIES=""

PL_LINK_DIRECTORIES=""

PL_COMPILER_FLAGS="-g "

PL_LINKER_FLAGS="-ldl "

PL_STATIC_LINK_LIBRARIES=""

PL_DYNAMIC_LINK_LIBRARIES=""

PL_SOURCES="main.c "



# run compiler (and linker)

echo

echo ${YELLOW}Step: tutorial${NC}

echo ${YELLOW}~~~~~~~~~~~~~~~~~~~${NC}

echo ${CYAN}Compiling and Linking...${NC}

gcc $PL_SOURCES $PL_INCLUDE_DIRECTORIES $PL_DEFINES $PL_COMPILER_FLAGS $PL_INCLUDE_DIRECTORIES $PL_LINK_DIRECTORIES $PL_LINKER_FLAGS $PL_STATIC_LINK_LIBRARIES $PL_DYNAMIC_LINK_LIBRARIES -o "./out/tutorial"



# check build status

if [ $? -ne 0 ]

then

    PL_RESULT=${BOLD}${RED}Failed.${NC}

fi



# print results

echo ${CYAN}Results: ${NC} ${PL_RESULT}

echo ${CYAN}~~~~~~~~~~~~~~~~~~~~~~${NC}



# hot reload skip

fi



# delete lock file(s)

rm -f "out/lock.tmp"



# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

# end of debug

fi





# return CWD to previous CWD

popd >/dev/null

Project details

These details have not been verified by PyPI

Project links

Homepage

Release history Release notifications | RSS feed

1.0.11

Oct 17, 2024

1.0.10

Oct 16, 2024

1.0.9

Oct 4, 2024

1.0.8

Oct 3, 2024

1.0.7

Sep 27, 2024

1.0.6

Sep 11, 2024

This version

1.0.5

Sep 6, 2024

1.0.4

Sep 6, 2024

1.0.3

Sep 6, 2024

1.0.2

Sep 6, 2024

1.0.1

Sep 5, 2024

1.0.0

Sep 5, 2024

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pl_build-1.0.5.tar.gz (17.9 kB view hashes)

Uploaded Sep 6, 2024 Source

Built Distribution

pl_build-1.0.5-py3-none-any.whl (18.9 kB view hashes)

Uploaded Sep 6, 2024 Python 3

Hashes for pl_build-1.0.5.tar.gz

Hashes for pl_build-1.0.5.tar.gz
Algorithm	Hash digest
SHA256	`6aca6391c3c0e61df07b6f980c1926955be96729151b29ffe06bcf9be5aac73b`
MD5	`f085fc90d2cb470cf06efb03391b6dba`
BLAKE2b-256	`99d9f31dd85778ecb53ca177b87d0f95103446d7319535a09775f079f18a21f0`

Hashes for pl_build-1.0.5-py3-none-any.whl

Hashes for pl_build-1.0.5-py3-none-any.whl
Algorithm	Hash digest
SHA256	`01ca06b680fc24dd6e68e8b67bdc5077d9340d202b23c9283865a5e70e7ba6d0`
MD5	`8e63bcda172661f33489e18e558977d4`
BLAKE2b-256	`8d602c13c1540dc893d011db279f563bd7344eac7f2c69b1149174c17e07dedb`