Skip to content

Latest commit

 

History

History
290 lines (195 loc) · 7.32 KB

cli.md

File metadata and controls

290 lines (195 loc) · 7.32 KB

Alce Command Line Interface

Table of Contents

  1. Introduction
  2. Requirements
  3. How to Use
  4. alce init
  5. alce compile
  6. alce run
  7. alce generate

Introduction

The Alce Command Line Interface (CLI) facilitates the construction and administration of Alce projects directly from a command shell.

It offers essential functionalities tailored for seamless project development and management, empowering users to efficiently handle various tasks associated with Alce projects within a command-line environment.

Requirements

  • Windows 10, 11 (64/32bit)
  • GCC v13.1.0^

Optional:

  • Python v3.1.0^ (if you want to execute the source code)

How to Use

To utilize the CLI, navigate to the ./Build directory within your project context.

cd ./Build

Within this directory, you'll find 2 folders:

  • Assets: This folder serves as the asset repository for your project, where you should store all game resources.

  • SFML-2.6.1: This directory contains SFML stuff. Do not delete this folder.

Additionally, there are 3 files:

  • cli.py: This file contains the source code for the CLI. You have full freedom to modify it. To use it instead of the official executable, replace the "./Build/alce" command with "python3 ./Build/cli.py".

  • settings.json: This file holds essential project data such as name, icon, and the current compiler binary path (which is undefined by default but may be necessary for certain CLI commands).

  • alce.exe: This file is the official executable for the CLI.

alce init

Command Syntax

./Build/alce [init, i]

Creates the required configuration file "Build/Settings.json" with the next fields:

  • Compiler:
    • "bin-path": the bin path of the MinGW32 compiler.
  • Project:
    • "name": Name of the current project.
    • "icon": .ico file for the executable.

alce compile

Command Syntax

./Build/alce [compile, c] [alias, a]=<alias_name> [mode, m]=<development|release> [--full, -f]|[--express, -e]

Compiles the project using an alias name.

Compilation Method

There are two compilation methods available:

  • Full Compilation: This method includes all files inside the ./Source folder in the compilation queue. It is recommended for releases and major tests.

  • Express Compilation: This method only includes the last modified files inside the ./Source folder in the compilation queue. It is recommended for minor changes and quick adjustments.

Once compilation succeeded, output files are generated inside the ./Build/Out folder, following the next scheme:

Build
  |-> Out
  |    |-> alias_name
  |    |     |-> Assets 
  |    |     |  alias_name.exe
  |    |     |  (.dll files)
  |  alce.exe

Note: The use of express compilation does not involve the compilation of affected files; it solely adds modified files to the compilation queue.

Build Mode

There are two build modes available:

  • Development: In this mode, the project execution will be accompanied by a debugging console.
  • Release: In this mode, the project execution will be clean and free of debugging information.

Default values:

  • Compilation method: --full
  • Build Mode: mode=development

Usage Examples

Compile the project using default values:

./Build/alce compile alias=<your_project_alias> 
./Build/alce c a=<your_project_alias>

Compile the project using the express method:

./Build/alce compile alias=<your_project_alias> --express
./Build/alce c a=<your_project_alias> -e

Compile the project using the full method:

./Build/alce compile alias=<your_project_alias> --full
./Build/alce c a=<your_project_alias> -f

Compile the project using the full method as a release:

./Build/alce compile alias=<your_project_alias> mode=release --full
./Build/alce c a=<your_project_alias> m=release -f

Compile the project in development mode:

./Build/alce compile alias=<your_project_alias> mode=development
./Build/alce c a=<your_project_alias> m=development

alce run

Command Syntax

./Build/alce [run, r] [alias, a]=<your_project_alias> [--standard, -std]|[--debug, -d]

Runs the project by alias name.

Run Mode

There are two run modes available:

  • Standard Mode: Runs the project as a standard application.
  • Debug Mode: Runs the project with GDB, the GNU project debugger.

Note: the use of --debug mode could affect the performance of the project.

Default Values:

  • Run Mode: --standard

Usage Examples

Run the project by alias name using default values

./Build/alce run alias=<your_project_alias>
./Build/alce r a=<your_project_alias>

Run the project by alias name using the GDB debugger

./Build/alce run alias=<your_project_alias> --debug
./BUild/alce r a=<your_project_alias> -d

Run the project by alias name as a standard application

./Build/alce run alias=<your_project_alias> --standard
./Build/alce r a=<your_project_alias> -std

alce generate

Generates various entities within the project context, streamlining development processes.

Generate Component

Command Syntax

./Build/alce generate component=<ComponentName>
./Build/alce g c=<ComponentName>

Creates a new component within the designated directory structure.

File Structure

Source
  |-> Alce
  |    |-> Engine
  |    |     |-> Components
  |    |     |     |-> (New Component)

Generate Scene

Command Syntax

./Build/alce generate scene=<SceneName>
./Build/alce g s=<SceneName>

Creates a new scene within the specified directory structure.

File Structure

Source
  |-> Project
  |    |-> Scenes
  |    |     |-> (New Scene)

Generate Object

Command Syntax

./Build/alce generate object=<SceneName>@<ObjectName>
./Build/alce g o=<SceneName>@<ObjectName>

Generates a new game object within a designated scene.

File Structure

Source
  |-> Project
  |    |-> Scenes
  |    |     |-> (Scene)
  |    |     |     |-> (New Game Object)

Generate Implementation

Generates the implementation of declarations within a .hpp file. Placing a comment //@impl above a declaration in the .hpp file triggers the creation of the basic structure within the corresponding .cpp file's implementation region, expediting the development process.

For instance, given the declaration in the .hpp file:

class Particle
{
  //@impl
  void SetDensity(float density);
};

The following structure will be generated in the respective .cpp file within the implementation region:

#pragma region implementation

  void Particle::SetDensity(float density)
  {
    
  }

#pragma endregion