PTXdist is a build system for creating embedded linux distributions, with a focus on industrial applications.
It is intended to be fully reproductible without external dependencies like toolchains and features time-based releases roughly once a month.

Basic mindset

Any PTXdist project consists of two components, plus the toolchain:

the Board Support Package (BSP)

the PTXdist release

You can think of a particular PTXdist release as of the distribution version/release, and of the BSP as what makes the distribution fit your device and application. In contrast to OpenEmbedded for example, this is a 1:1-relation. PTXdist does not support the combination or overlaying of several BSPs or patchsets.
As the 1:1-relation suggests, a BSP is tied fairly tight to a specific ptxdist version in the first place. Hence, if if you are just getting into PTXdist and the question is "Which version do i need?", then the answer is: "Look at your BSP."

Getting started

You usually start with the BSP that comes with the hardware you purchased, or a generic one if you want to create one for your own project. The instructions given here apply directly to the Generic ARM BSP, but should need only very little adjustment to for other BSPs.

Picking the correct PTXdist version

The easiest was is to look at the config file. It usually is located in

configs/ptxdist

of the BSP. The comment lines at the top of the files will tell you the ptxdist version to get.

Preparing and compiling PTXdist

If you are working on more than one project, you will probably need a variety of ptxdist versions and toolchains. A directory layout that has proved to work pretty well is:

/ptxdist/releases
/toolchains
/sources
/projects/A
/B
/C

So you will put all your untarred ptxdist releases into /ptxdist/releases and just use them from there. Prior to compiling, you will probably need to get the dependencies (example is for debianoids):

This creates a symplink named "p" in your BSP directory. From now on, you can always reference the correct PTXdist version though that link.

First time setup

If this is the first time you are using PTXdist on that computer, it is now time to create a minimal setup. Start

./p setup

in your BSPs directory and you are presented a Kconfig-UI. It is strongly recommended to change

Source Directories->Source Directory

to your /ptxdist/sources path. That way all BSPs and Toolchains can share one common directory for the downloaded sources packages, which will save you a considerable amount of download time and disk space if you are working on more than one non-trivial BSP.

Selecting the platform

After selecting the ptxconfig, its time to pick the platform configuration. A BSP can contain a number of platform configurations on which the software shall be able to run. A common use case is a board that can be equipped with various flash sizes, for example. But of course also very high varieties between platform configurations are possible. In the case of the generic BSP, we pick:

./p platform configs/arm-qemu-2011.11.0/platformconfig

which will in turn try to find and select the fitting toolchain.

Building the toolchain

If it is the first time that you have fired up the above commands, probably PTXdist will complain about not being able to find the toolchain. That means that you have to build it first. That works just like the process for the BSP given above, for PTXdist-created toolchains are basically just a little special BSPs.
As most PTXdist BSP use the OSELAS toolchains, you just need to get the Toolchain BSP that your BSP just complained about not finding from here, place the extracted directory in /ptxdist/toolchains and repeat the above process, picking the wanted toolchain through

./p select ptxconfigs/xxxxxxxx

After that, it is time to actually build the toolchain: You start the PTXdist build process through

./p go

If you want to limit the load on your box a bit, you can use instead

./p go -ji X

with X being the maximum amount of processes used for compiling. Compilation takes about 30minutes on an average developer box nowadays. The toolchain gets place in the /opt directory hierachya and becomes write-protected, so it usually is necessary that you accept and authorized sudo to do the needed user/rights changes.
After having built the toolchain, you can change back to the project directory, re-run the platform configuration selection and the toolchain should be successfully detected.

Finally building the BSP

Back in you BSP directory, you start the build with

./p go

to which you can of course also add a -ji switch again if you like. And finally, after an amount of time depending on your BSP and the selected software packages, you can find your created root file system in the platform-{$PROJECTNAME}/root directory

Optional: creating filesystem images

If the platform configuration is set to support the creation of filesystem images, you can create them with