web analytics
How to create a new component

Short story

The Ada Crate / Lib / App _Template is on AdaForge GitLab

Direct to section:

Direct to 👩🏻‍💻

AdaForge Project Templates

« Stainless Steel Ada code will never Rust » ™ 🤣

Objectives

🏀 Ada Pkg Units

🏈 Sources Repo

⚽️ Distrib Repo

Use cases

  1. Structure or integrate a new Ada Lib Package in your code
  2. Use or publish new Crates / Lib Components
    • Building the Binary exe or library file
  3. Packaging for download and install
    • Linux APT or RPM
    • FreeBSD Pkg
    • MacOS DMG
    • Windows App Installer

Challenges

✏️ Names-spaces

Define & Structure the 3 name-spaces without name clashing

⚠️ Constraints

  • Ada Pkg Units : Give some functional meaning
  • Sources Repo : Diffenciate 3 (or more) proposals/authors for a same functional domain, say XML, AES, advanced String lib, ...
  • Distrib Repo : Must be unique all-round on some environnements

Design

📚 3 catalogues with organized levels of hierarchy

Ada

  1. Ada Unit-Name of your code -- or libraries to use
    • 3 Levels of hierarchy + your Unit name

Sources Repo

  1. Crate / Lib Component name
    • 2 Levels of hierarchy + your Crate short name
    • Binary exe or library file short name

Distrib Repo

  1. Distrib package name
    • 1 Level of hierarchy // but your Pkg short name must be unique

🎯 Benchmarking

Ada Pkg Units

Libs

Distrib

In practice

Base Hierarchy

Owner - Pkg1 - Pkg2 - Component

Note: Owner = Copyright owner (author ?)

🏀 Ada Pkg Units

  • Owner.Pkg1.Pkg2.Component (API Unit)
  • Owner.Pkg1.Pkg2.Component.*
  • Owner.Pkg1.Pkg2.Component_* (for high-level dependencies)
  • Owner _ Pkg1 _ Pkg2 _ Component _ * (main public programs)

🏈 Crate / Lib names

  • Full name : Owner _ Pkg1 _ Pkg2 _ Component
  • Short name = ownepkg1pkg2comp
  • ALIRE Crate name in alire.toml = : owner _ pkg1 _ pkg2 _ component
  • GPR main build file = : owner _ pkg1 _ pkg2 _ component .gpr

Crates / Libs AdaForge's catalogue

  • AdaForge Source Repo (GitLab: 2 sub-groups + project) =
    • pkg1 / pkg2 / ownepkg1pkg2comp
    • _Authors / owner
    • _Authors / ownerpkg1
    • _Authors / ownerpkg1pkg2

Crate / Lib (short) unique name

  • Short name = ownepkg1pkg2comp

How to hash the short name :

$ touch owner_pkg1_pkg2_component
$ gnatkr owner_pkg1_pkg2_component  16
> ownepkg1pkg2comp

⚽️ Distrib Catalogue

Project artefacts are stored in

  • pkg1 / ownepkg1pkg2comp

Project Structure

Recommanded dir-folder name =

component short name =

ownepkg1pkg2comp

📐« Configuration as Code » ™

Base principles :

  1. Follow as much as possible Alire default configuration
  2. All sources under ./src
  3. All tests materils as a sub-project under ./tests
  4. All build configuration and scripts under ./bld
  5. All build artefacts under ./build
  6. Head build files are in ./.
    • alire.toml
    • Makefile
    • owner_pkg1_pkg2_component.gpr

🏠« User feels at home » ™

Base principles :

  1. All doc under ./doc
  2. All resource files (not having merging capabilities) under ./resources
  3. All licenses files in ./LICENSES
  4. Use as possible MarkDown GLFM flavor syntax for text files
    • README.md
    • NOTICE.md

📣 « Show what is public » ™

Base principles :

  1. All API files in ./src/lib
  2. All MAIN source files in ./src/main
  3. All TEST main-programs source files and data in ./tests/main ./tests/data

🗄️ « Hide what is private » ™

Base principles :

  1. All other Lib files are under ./src/lib/sub/**
  2. All other MAIN sub-units source files under ./src/main/sub/**
  3. All other TEST sub-units source files are under ./tests/main/sub/**

Custom Alire defaults

  • Main project GPR build file
  • We group all build definitions and scripts under ./bld (no Alire ./config)

So we have to set: [WIP]

./alire.toml

[configuration]
auto_gpr_with = false
output_dir = "bld"

./tests/alire.toml

[configuration]
auto_gpr_with = false
output_dir = "bld"

EEC GDPR compliant