====== Development Environment ======

The AstLinux Development Environment (ADE) is maintained in a repository on GitHub.

AstLinux is cross-compiled, generating target images for x86_64 CPU architectures, using a custom maintained version of [[https://buildroot.org|Buildroot]].
===== Linux Build System =====

Building AstLinux requires using some version of Debian Linux. A 64-bit, x86_64 build system is required.

Using a Virtual Machine is suggested, minimal recommended configuration:

  * 64 GB Storage
  * 2 GB RAM
  * 1-2 CPU Cores

Linux Build Systems known to work **(must be x86_64)**:

  * Debian 11
  * Debian 12 - //(recommended)//

!!Tip ->!! Use a somewhat older LTS (Long Term Support) Linux distro in a VM, that will be the most compatible with our version of Buildroot.

!!Tip ->!! Use a "Minimal Install" of your Linux distro, dedicated to building AstLinux.

===== Promox notes =====

!!Tip ->!! To run Debian 10/11 in a LXC container on Proxmox 6/7/8, you need to enable "Nesting" under "Options/Features", otherwise you'll end up getting "Permission denied" errors when starting several services (e.g. apache2, ntp). Creating a Flash Image does **not** work in a LXC container (you need a "full" VM for this)!

!!Tip ->!! There seems to be a problem when running the "Linux Build System" in Proxmox as __LXC container__ **AND** __on a ZFS filesystem__. If you get errors like this:
  genext2fs: couldn't allocate a block (no free space)
although there is plenty of free space. It doesn't happen when running the filesystem on LVM or LVM-thin.

===== Prerequisites =====

To build Astlinux you first need to install some additional packages:

**[[.packages|Package lists]]**

===== Getting Started =====

These instructions will show you how to build AstLinux from the "trunk" branch.

After you have installed the prerequisite packages (per above), switch to your $HOME directory on your machine **as a regular user (non-root):**

  cd ~

Create the "astlinux" directory for the AstLinux source:

  mkdir astlinux

!!Important ->!! You should **not be root**, login as a non-admin user.
===== Checking out the Source =====
Now we will grab AstLinux via ''git'': 

  git clone https://github.com/astlinux-project/astlinux.git astlinux/trunk

You should see a bunch of files scroll down your machine. Depending on the speed of your connection, this could take a few seconds or a minute.

Once the clone process has completed, cd into astlinux/trunk to look around:

  cd astlinux/trunk
===== First Build =====
The AstLinux Development Environment is based on the excellent [[http://buildroot.uclibc.org/|Buildroot]] build system.  The cross-compile toolchain is created with the excellent [[http://crosstool-ng.org/|Crosstool-NG]].

Next we will copy the default AstLinux config file and look for any new configure options.

Copy the default AstLinux config file (example with Asterisk 18):

  cp x86_64-configs/astlinux-ast18.config .config

Check for new configure options:

  make oldconfig
  
If you get "make: command not found" or a similar error you will need to install some development tools before you can continue. See **[[.packages|Package lists]]** for more information.

Next, create the cross-compile toolchain. Carefully follow these [[https://raw.githubusercontent.com/astlinux-project/astlinux/master/crosstool-ng-src/README|Crosstool-NG Instructions]].  Should you skip this step, **''./scripts/build''** will generate an error with the same instructions.

If this is your first time building AstLinux we suggest that you don't make any changes to the default AstLinux configuration. This will make it easier to troubleshoot any problems you might have. Now it's time to start the build:

  ./scripts/build genx86_64

The script ''./scripts/build'' is a wrapper that checks for certain tools and sets up the environment prior to issuing ''make''. If you run ''make'' manually, you will not generate a complete build.

The option "genx86_64" is the board type, other board types are: genx86_64-serial and genx86_64-vm.  If this option is omitted, the previous board type built will be used.  The "genx86_64" board uses a VGA/video console, while the "genx86_64-serial" board uses a 115200 baud serial console.

!!Info ->!! [[devdoc:boardtypes|List of board types]]

The ADE will take an hour or two to build, depending on the speed of your system and internet connection.
===== Custom Build =====
After building the complete system the first time, you can modify the package selections by issuing the following command prior to ''./scripts/build''.

  make menuconfig 

To start a fresh, clean build, remove the "output" directory and start a new build:

  rm -rf output
  ./scripts/build
  
All board types use the same x86_64 toolchain, so after ''./scripts/build genx86_64'' completes you can issue ''./scripts/build genx86_64-serial'' and it will take less than a minute to create the new build for that board type.

Of special note, there are two kernel configurations supported.

For 64-bit SMP kernel builds: (boards with x86_64 multi-core processors)

  project/astlinux/genx86_64/linux-smp.config

For 64-bit VM kernel builds: (optimized for x86_64 virtual machines containing VM drivers)

  project/astlinux/genx86_64/linux-smp-vm.config

Use **''make menuconfig''** to specify which kernel configuration to use.  Changing the kernel configuration requires a fresh, clean build.
===== Create a Flash Image =====
[[devdoc_create_image|Create a Flash Image]]

===== Create an ISO Installer =====
[[devdoc_create_iso_installer|Create an ISO Installer]]

===== Create a Private Repository =====
[[devdoc_create_repository|Create a Private Repository]]

===== Switching Images between i586 and x86_64 =====
[[devdoc_switch_i586_x86_64|Switching Images between i586 and x86_64]]

===== Switching Images between genx86_64 and genx86_64-vm =====
[[devdoc_switch_genx86_64_and_vm|Switching Images between genx86_64 and genx86_64-vm]]

===== Tips and Tricks =====

[[[devdoc-custom-webgui|Create Custom Web Interface Tabs]]