toys/adtools-light

• Advanced Build Tools
• • Installation
  • • Configuration
    • Build Tool - admake
    • Git Helper Tools - adgit
    • Best Practice
  • FAQ

Advanced Build Tools

Installation

Run the installation command, then you can run AD tools(just like admake, adgit) everywhere.

NOTE: On Ubuntu 24.04+ or Debian 12+, you should replace pip with pipx, install it first: sudo apt install pipx -y

# Install dependencies
python3 -m pip install -U build setuptools wheel

# Install adtools from source locally
# Install into the user enviroment($HOME/.local/lib)
python3 -m pip install --user .
# Or install into system wide environment or conda environment
python3 -m pip install .

# Or
# Build the package
pyproject-build --wheel

# Install the whl package
python3 -m pip install dist/*.py --user

NOTE: In China mainland, use a mirror PyPI repository is a better choice: pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

Configuration

If you want to use admake to manage third-party packages,
there are two ways: downloading from a Nexus3 service(automatically by admake)
or importing from a local file system(admake import -i ...).

The first method is recommended, but you have to do some configurations for the Nexus3 service:
three environment variables in your terminal environment:

• NEXUS_HOST: The base URL of your Nexus3 service, e.g. http://172.23.140.35:8088. REQUIRED
• NEXUS_USERNAME: The username of your Nexus3 account that has the accessable permission. OPTIONAL
• NEXUS_PASSWORD: The corresponding password of your Nexus3 account. OPTIONAL

You can export the environment variables in your rc files(.zshrc/.bashrc) like the following:

The following username and password are just examples,
please contact the administrator for the corresponding
account information, if you want to access the repo
anonymously, just comment them or leave them empty("").

export NEXUS_HOST="http://172.23.140.35:8088"
export NEXUS_USERNAME="anonymous"
export NEXUS_PASSWORD="anonymous"

If your Nexus3 service allow anonymous user to read, the last two environment variables is not required.
But maybe you can not publish packages to the service(admake publish need the write permission).

Build Tool - admake

Typical usage:

admake build
admake rebuild

Create custom targets with CMake CMAKE_TOOLCHAIN_FILE:

# Create the directory in your project if it does not exist.
mkdir -p cmake/targets
# Put the target .cmake file into the directory `cmake/targets`
# NOTE: the name of the `.cmake` file should be the same as `-p` option.
touch cmake/targets/arm64.cmake
# Edit the `.cmake` file, in this case: emacs cmake/targets/arm64.cmake
# ...

# Build with your own `CMAKE_TOOLCHAIN_FILE`
admake build -p arm64

Git Helper Tools - adgit

In fact, adgit is a proxy, proxy the git commands(subset)
for all the sub-projects records in .adgitrc file.
So all the sub-commands and corresponding arguments are the same as git.

# Print all the supported sub-commands and help message
adgit -h
# Clone all the repositories you can access
# Usually it is the first command you should run
# after clone the master project `tools`.
adgit clone
# Pull all the repositories you can access
adgit pull
# Fetch all
adgit fetch -a -p
# Switch branch
adgit checkout newbranch

Best Practice

There are two ways to organize your project when you are working with admake and adgit:

• Create a workspace then clone all the related repos into this directory,
  if a repo is depended by more than one workspace, you have to clone it multi times.
• Clone all the repos in a big workspace, then create independent subworkspaces,
  then create symbolic links into the subworkspaces.

So that, when you import modules via append_modules,
the admake can scan the workspace for you automatically,
and adgit will operate all the repos in the same workspace when you ignore .adgitrc.

FAQ

If you encounter any problems during using admake or adgit, please refer to the FAQ document.