Home

Awesome

xcpkg

A package builder/manager for Xcode to build projects written in C, C++, Rust, Zig, Go, etc.

Caveats

Using xcpkg via GitHub Actions

In this way, you will be liberated from the rut of setting up the build environment.

In this way, all you need to do is just clicking the buttons and waiting for finishing. After finishing, a url refers to a zip archive will be provided to download.

For more details please refer to https://github.com/leleliu008/xcpkg-package-manually-build

Install xcpkg via cURL

curl -LO https://raw.githubusercontent.com/leleliu008/xcpkg/master/xcpkg
chmod a+x xcpkg
./xcpkg setup

Install xcpkg via wget

wget https://cdn.jsdelivr.net/gh/leleliu008/xcpkg/xcpkg
chmod a+x xcpkg
./xcpkg setup

Install xcpkg via git

git clone --depth 1 https://github.com/leleliu008/xcpkg
xcpkg/xcpkg setup

~/.xcpkg

all relevant directories and files are located under ~/.xcpkg directory.

xcpkg command usage

influential environment variables

environment variables unset by this software

ENVused by
SDKROOTclang clang++
MACOSX_DEPLOYMENT_TARGETclang clang++
WATCHOS_DEPLOYMENT_TARGETclang clang++
IPHONEOS_DEPLOYMENT_TARGETclang clang++
TARGET_ARCHgmake

environment variables override by this software

ENVused by
CCconfigure
CXXconfigure
CPPconfigure
ASconfigure
ARconfigure
LDconfigure
CFLAGSconfigure
CXXFLAGSconfigure
CPPFLAGSconfigure
LDFLAGSconfigure
LIBSconfigure
CMAKE_GENERATORcmake
CMAKE_BUILD_PARALLEL_LEVELcmake
CMAKE_EXPORT_COMPILE_COMMANDScmake
RUST_BACKTRACEcargo
RUSTFLAGScargo
CARGO_BUILD_JOBScargo
CARGO_BUILD_TARGETcargo
CARGO_BUILD_TARGET_DIRcargo
CGO_ENABLEDgo
CGO_CFLAGSgo
CGO_CXXFLAGSgo
CGO_CPPFLAGSgo
CGO_LDFLAGSgo
GO111MODULEgo
GOOSgo
GOARCHgo
PKG_CONFIG_LIBDIRpkg-config
PKG_CONFIG_PATHpkg-config
PKG_CONFIG_DEBUG_SPEWpkg-config
ACLOCAL_PATHaclocal
XDG_DATA_DIRSg-ir-scanner
XML_CATALOG_FILESxsltproc
PERL_MM_USE_DEFAULTcpan
BAT_THEMEbat
IFSshell

xcpkg formula scheme

a xcpkg formula is a YAML format file which is used to config a xcpkg package's meta-information including one sentence description, package version, installation instructions, etc.

a xcpkg formula's filename suffix must be .yml

a xcpkg formula'a filename prefix would be treated as the package name.

a xcpkg formula'a filename prefix must match regular expression pattern ^[A-Za-z0-9+-._@]{1,50}$

a xcpkg formula's file content only has one level mapping and shall has following KEY:

KEYrequired?overview
pkgtypeoptionalindicates what type of this package. value shall be any one of exe, lib, exe+lib.<br>If this mapping is not present, xcpkg will determine the package type by package name, if a package name starts/ends with lib, it would be recognized as type lib, otherwise, it would be recognized as type exe
summaryrequireddescribe this package in one sentence.
licenseoptionala space-separated list of SPDX license short identifiers
versionoptionalthe version of this package.<br>If this mapping is not present, it will be calculated from src-url, if src-url is also not present, it will be calculated from running time as format date +%Y.%m.%d
web-urloptionalthe home webpage of this package.<br>If this mapping is not present, git-url must be present.
git-urloptionalthe source code git repository.<br>If src-url is not present, this mapping must be present.
git-refoptionalreference: https://git-scm.com/book/en/v2/Git-Internals-Git-References <br>example values: HEAD refs/heads/master refs/heads/main refs/tags/v1, default value is HEAD
git-shaoptionalthe full git commit id, 40-byte hexadecimal string, if git-ref and git-sha both are present, git-sha takes precedence over git-ref
git-nthoptionaltell xcpkg that how many depth commits would you like to be fetched. default is 1, this would save your time and storage. If you want to fetch all commits, set this to 0
src-urloptionalthe source code download url of this package.<br>If value of this mapping ends with one of .zip .tar.xz .tar.gz .tar.lz .tar.bz2 .tgz .txz .tlz .tbz2 .crate, it will be uncompressed to $PACKAGE_WORKING_DIR/src when this package is installing, otherwise, it will be copied to $PACKAGE_WORKING_DIR/src<br>also support format like dir://DIR
src-urioptionalthe mirror of src-url.
src-shaoptionalthe sha256sum of source code.<br>src-sha and src-url must appear together.
fix-urloptionalthe patch file download url of this package.<br>If value of this mapping ends with one of .zip .tar.xz .tar.gz .tar.lz .tar.bz2 .tgz .txz .tlz .tbz2 .crate, it will be uncompressed to $PACKAGE_WORKING_DIR/fix when this package is installing, otherwise, it will be copied to $PACKAGE_WORKING_DIR/fix.
fix-urioptionalthe mirror of fix-url.
fix-shaoptionalthe sha256sum of patch file.<br>fix-sha and fix-url must appear together.
fix-optoptionaloptions to be passed to patch command. default value is -p1.
patchesoptionalmultiple lines of <fix-sha>|<fix-url>[|fix-uri][|fix-opt].
res-urloptionalother resource download url of this package.<br>If value of this mapping ends with one of .zip .tar.xz .tar.gz .tar.lz .tar.bz2 .tgz .txz .tlz .tbz2 .crate, it will be uncompressed to $PACKAGE_WORKING_DIR/res when this package is installing, otherwise, it will be copied to $PACKAGE_WORKING_DIR/res.
res-urioptionalthe mirror of res-url.
res-shaoptionalthe sha256sum of resource file.<br>res-sha and res-url must appear together.
reslistoptionalmultiple lines of <res-sha>|<res-url>[|res-uri][|unpack-dir][|N]. unpack-dir is relative to $PACKAGE_WORKING_DIR/res, default value is empty. N is --strip-components=N
dep-pkgoptionala space-separated list of xcpkg packages that are depended by this package when installing and/or runtime, which will be installed via xcpkg.
dep-uppoptionala space-separated list of uppm packages that are depended by this package when installing and/or runtime, which will be installed via uppm.
dep-pymoptionala space-separated list of python packages that are depended by this package when installing and/or runtime, which will be installed via pip3.
dep-plmoptionala space-separated list of perl modules that are depended by this package when installing and/or runtime, which will be installed via cpan.
ccflagsoptionalappend to CFLAGS
xxflagsoptionalappend to CXXFLAGS
ppflagsoptionalappend to CPPFLAGS
ldflagsoptionalappend to LDFLAGS
bsystemoptionalbuild system name.<br>values can be one or a combination of autogen autotools configure cmake cmake+gmake cmake+ninja meson xmake gmake ninja cargo go rake
bscriptoptionalthe directory where the build script is located in, relative to PACKAGE_WORKING_DIR. build script such as configure, Makefile, CMakeLists.txt, meson.build, Cargo.toml, etc.
binbstdoptionalwhether to build in the directory where the build script is located in, otherwise build in other directory.<br>value shall be 0 or 1. default value is 0.
symlinkoptionalwhether to symlink installed files to $XCPKG_HOME/symlinked/*.<br>value shall be 0 or 1. default value is 1.
movableoptionalwhether can be moved/copied to other locations.<br>value shall be 0 or 1. default value is 1.
paralleloptionalwhether to allow build system running jobs in parallel.<br>value shall be 0 or 1. default value is 1.
onstartoptionalPOSIX shell code to be run when this package's formula is loaded.<br>PWD is $PACKAGE_WORKING_DIR
onreadyoptionalPOSIX shell code to be run when this package's needed resources all are ready.<br>PWD is $PACKAGE_BSCRIPT_DIR
onfinaloptionalPOSIX shell code to be run when this package is successfully installed.<br>PWD is $PACKAGE_INSTALL_DIR
do12345optionalPOSIX shell code to be run for native build.<br>It is running in a separated process.
dopatchoptionalPOSIX shell code to be run to apply patches manually.<br>PWD is $PACKAGE_BSCRIPT_DIR
prepareoptionalPOSIX shell code to be run to do some additional preparation.<br>PWD is $PACKAGE_BSCRIPT_DIR
installoptionalPOSIX shell code to be run when user run xcpkg install <PKG>. If this mapping is not present, xcpkg will run default install code according to bsystem.<br>PWD is $PACKAGE_BSCRIPT_DIR if binbstd is 0, otherwise it is $PACKAGE_BCACHED_DIR
dotweakoptionalPOSIX shell code to be run to do some tweaks immediately after installing.<br>PWD is $PACKAGE_INSTALL_DIR
caveatsoptionalmultiple lines of plain text to be displayed after installation.
phases of a package's installation
phases
build system namebuild script file name
mesonmeson.build
cmakeCMakeLists.txt
gmakeGNUMakefile or Makefile
ninjabuild.ninja
xmakexmake.lua
cargoCargo.toml
gogo.mod
rakeRakefile
autogenautogen.sh
autotoolsconfigure.ac
configureconfigure

commands that can be used out of the box:

commandusage-example
bashReference
CoreUtilsReference
xargsReference
findReference
gawkReference
gsedReference
grepReference
jqReference
yqReference
d2Reference
batReference
gitReference
curlReference
treeReference
bsdtarReference
pkg-configReference
echoecho 'your message.'
infoinfo 'your information.'
warnwarn "no package manager found."
errorerror 'error message.'
abortabort 1 "please specify a package name."
successsuccess "build success."
isIntegerisInteger $x || abort 1 "should be an integer."
isCrossBuildisCrossBuild && abort 1 "This package is not supposed to be cross built."
wfetchwfetch <URL> [--uri=<URL-MIRROR>] [--sha256=<SHA256>] [-o <PATH> [-q]
configureconfigure --enable-pic
mesonwmesonw -Dneon=disabled -Darm-simd=disabled
cmakewcmakew -DBUILD_SHARED_LIBS=ON -DBUILD_STATIC_LIBS=ON
gmakewgmakew
xmakewxmakew
cargowcargow
gowgow

shell variables can be used directly:

variableoverview
TIMESTAMP_UNIXthe unix timestamp of this action.
NATIVE_PLATFORM_KINDcurrent running platform kind. value shall be darwin
NATIVE_PLATFORM_TYPEcurrent running platform type. value shall be macos
NATIVE_PLATFORM_NAMEcurrent running platform name. value shall be MacOSX
NATIVE_PLATFORM_VERScurrent running platform version.
NATIVE_PLATFORM_ARCHcurrent running platform arch. value might be any one of x86_64, arm64, etc
NATIVE_PLATFORM_NCPUcurrent running platform's cpu core count.
NATIVE_PLATFORM_EUIDcurrent running platform's effective user ID.
NATIVE_PLATFORM_EGIDcurrent running platform's effective group ID.
TARGET_PLATFORM_NAMEtarget platform name that is built for. value shall be any one of AppleTVOS AppleTVSimulator DriverKit MacOSX WatchOS WatchSimulator iPhoneOS iPhoneSimulator
TARGET_PLATFORM_VERStarget platform version that is built with.
TARGET_PLATFORM_ARCHtarget platform arch that is built for. value might be any one of x86_64, arm64, etc
CROSS_COMPILINGvalue shall be 0 or 1. indicates whether is cross-compiling.
XCPKG_ARG0the 1st arguments of xcpkg that you've supplied.
XCPKG_ARG1the 2nd arguments of xcpkg that you've supplied.
XCPKG_ARGVthe all arguments of xcpkg that you've supplied.
XCPKG_PATHthe full path of xcpkg that you're running.
XCPKG_HOMEthe home directory of xcpkg that you're running.
XCPKG_VERSIONthe version of xcpkg that you're running.
UPPMthe executable filepath of uppm
CC_FOR_BUILDthe C Compiler for native build.
CFLAGS_FOR_BUILDthe flags of CC_FOR_BUILD.
CXX_FOR_BUILDthe C++ Compiler for native build.
CXXFLAGS_FOR_BUILDthe flags of CXX_FOR_BUILD.
CPP_FOR_BUILDthe C/C++ PreProcessor for native build.
CPPFLAGS_FOR_BUILDthe flags of CPP_FOR_BUILD.
AS_FOR_BUILDthe assembler for native build.
AR_FOR_BUILDthe archiver for native build.
RANLIB_FOR_BUILDthe archiver extra tool for native build.
LD_FOR_BUILDthe linker for native build.
LDFLAGS_FOR_BUILDthe flags of LD_FOR_BUILD.
NM_FOR_BUILDa command line tool to list symbols from object files for native build.
STRIP_FOR_BUILDa command line tool to discard symbols and other data from object files for native build.
CCthe C Compiler.
CFLAGSthe flags of CC.
CXXthe C++ Compiler.
CXXFLAGSthe flags of CXX.
CPPthe C/C++ PreProcessor.
CPPFLAGSthe flags of CPP.
ASthe assembler.
ARthe archiver.
RANLIBthe archiver extra tool.
LDthe linker.
LDFLAGSthe flags of LD.
NMa command line tool to list symbols from object files.
STRIPa command line tool to discard symbols and other data from object files.
PACKAGE_WORKING_DIRthe working directory when installing.
PACKAGE_BSCRIPT_DIRthe directory where the build script (e.g. Makefile, configure, CMakeLists.txt, meson.build, Cargo.toml, etc) is located in.
PACKAGE_BCACHED_DIRthe directory where the temporary files are stored in when building.
PACKAGE_INSTALL_DIRthe directory where the final files will be installed to.
x_INSTALL_DIRthe installation directory of x package.
x_INCLUDE_DIR$x_INSTALL_DIR/include
x_LIBRARY_DIR$x_INSTALL_DIR/lib

xcpkg formula repository

a typical hierarchical structure of a xcpkg formula repository looks like below:

XCPKGFormulaRepoName
├── formula
│   ├── packageA.yml
│   └── packageB.yml
├── LICENSE
└── README.md

xcpkg formula repository local location

${XCPKG_HOME}/repos.d/${XCPKGFormulaRepoName}

xcpkg formula repository local config

a xcpkg formula repository's config file is located at ${XCPKG_HOME}/repos.d/${XCPKGFormulaRepoName}/.xcpkg-formula-repo.yml

a typical xcpkg formula repository's config file content looks like below:

url: https://github.com/leleliu008/xcpkg-formula-repository-official-core
branch: master
pinned: 0
enabled: 1
created: 1673684639
updated: 1673684767

If a xcpkg formula repository is pinned, which means it would not be updated.

If a xcpkg formula repository is disabled, which means xcpkg would not search formulas in this formula repository.

xcpkg formula repository management

run xcpkg formula-repo-add command to create a new formula repository locally from an exsting remote git repository.

run xcpkg formula-repo-init command to create a new formula repository locally without taking any further action.

xcpkg official formula repository

xcpkg official formula repository is hosted at https://github.com/leleliu008/xcpkg-formula-repository-official-core

It would be automatically fetched to your local repository as name official-core when you run xcpkg update command.

Note: If you find that a package is not in xcpkg official formula repository yet, PR is welcomed.

prebuild packages built by this software