APPSCRIPT(1) General Commands Manual APPSCRIPT(1) NAME appscript -- Simple, lightweight and effective tool for creating SFX files SYNOPSIS appscript -v appscript [-Ls] [-a arch] [-c algo] [-o filename] [-S sysroot] directory DESCRIPTION appscript is a very lightweight and easy-to-use tool for creating self-ex- tracting executables. From the developer's perspective, tar(1) is used to compress a directory into a tarball, known as the "payload," which is stored in the .rodata sec- tion, objcopy(1) to convert the payload into a valid elf(3)object file, and then clang(1) to compile the payload with the C-written stub. And from the user's perspective, it just need to run the executable file, and the magic happens behind the scenes: the AppScript (the SFX file) reads the addresses where the payload is located and uses libarchive(3) to extract the files to a temporary directory, finally executing an executable file named APPSCRIPT. The user can pass any environment variables and arguments to the AppScript, and the APPSCRIPT executable can handle them just like any other program or script. However, an AppScript does much more than what has been described above. First, it sets handlers for SIGHUP, SIGINT, SIGQUIT, SIGTERM, SIGXCPU, and SIGXFSZ to stop the AppScript when it's running. SIGALRM, SIGVTALRM, SIGPROF, SIGUSR1, and SIGUSR2 are ignored. Next, it checks if the /var/tmp/appscript directory exists and, if so, uses it to create temporary directories; otherwise, /tmp is used as fallback. The reason /var/tmp/appscript is preferred is that a system administrator can config- ure this location to mount a tmpfs(4) filesystem to improve the performance of very large AppScripts. This is more secure than setting "vfs.usermount=1" and letting the user (or, in this case, the user's process) mount a tmpfs(4) filesystem. Regardless of the directory used, it must have file mode 1777; otherwise, an EX_NOPERM error will be returned. After initial checks, the tarball is extracted to a temporary location de- termined by the directories mentioned above. The AppScript will refuse to extract absolute paths and entries containing periods, and will apply basic protection against symbolic links (see ARCHIVE_EXTRACT_SECURE_SYMLINKS in archive_write_disk(3)for details). Finally, if no signal is received and no errors are detected during the files extraction, the AppScript will at- tempt to execute the APPSCRIPT file. For this to succeed, the file must have the execute bit set and the owner must be the same as the effective uid, which should be the case since the uid and gid are changed to the caller when the files are extracted. As a final task, the temporary direc- tory is recursively removed in a similar way to the -r and -f flags in rm(1). APPSCRIPT runs in a new process group, and when its parent process (the AppScript executable) receives a handled signal (such as those mentioned above), it forwards the signal to the entire APPSCRIPT's process group. The options are as follows: -L All symbolic links will be followed. Normally, symbolic links are archived as such. With this option, the target of the link will be archived instead. -s Tells the linker to create a statically linked executable. -v Display version information about appscript. -a arch Specifies an architecture for the binary other than the default, which is the same as the host. Valid arguments are: amd64, aarch64, armv7, i386, riscv64 , powerpc, powerpc64, and powerpc64le. -c algo Compression algorithm to be used to compress the directory. Valid ar- guments: gzip, xz, and zstd. The default is zstd. -o filename Name of the resulting executable. By default, a.AppScript. -S sysroot Tells clang(1) to use a specified directory as the logical root direc- tory for resolving system headers and libraries. By default, when no argument is specified, it uses the /usr/local/freebsd-sysroot/arch directory only if it exists and if the host's machine architecture is the same as arch; otherwise, it falls back to /. If you have installed the arch-freebsd-sysroot package, this should work correctly, but this parameter is primarily necessary when you need to cross-compile a statically linked binary. directory Directory to be compressed. appscript assumes that the APPSCRIPT script is already present and has the execute bit set. ENVIRONMENT APPSCRIPT_PWD Since APPSCRIPT runs from the current user's working directory, it does not know the location of the temporary directory. This environ- ment variable specifies that location. APPSCRIPT_SCRIPT Absolute path to the AppScript that is currently running. EXAMPLES Improving performance If you are the sovereign of your system, users will appreciate you if you enable tmpfs(4) at /var/tmp/appscript for very large AppScripts: # /etc/fstab tmpfs /var/tmp/appscript tmpfs rw,size=1G,mode=1777,late 0 0 Then: # mkdir -p /var/tmp/appscript # mount /var/tmp/appscript The "Hello World" example To create the most basic AppScript all you have to do is create a direc- tory: $ mkdir hello-world Create the APPSCRIPT file: $ cat << EOF > ./hello-world/APPSCRIPT #!/bin/sh echo "Hello, world!" EOF And set the execute bit: $ chmod +x ./hello-world/APPSCRIPT To finally create the AppScript: $ appscript ./hello-world $ ls ./a.AppScript $ ./a.AppScript Hello, world! SEE ALSO tar(1) libarchive(3) signal(3) sysexits(3) AUTHORS JesAos Daniel Colmenares Oviedo <DtxdF@disroot.org> FreeBSD ports 15.quarterly June 03, 2026 APPSCRIPT(1)
NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | EXAMPLES | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=appscript&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>