From 03e2bc51d8cd0eedbbde1aea874a8a972bfb7464 Mon Sep 17 00:00:00 2001 From: Rachel Date: Sat, 10 Oct 2026 08:41:18 -0700 Subject: [PATCH] tools: Sync nitroarc from upstream (#1300) --- tools/nitroarc/doc/nitroarc.1.adoc | 51 ++++++-- tools/nitroarc/lib/include/nitroarc.h | 14 ++- tools/nitroarc/lib/nitroarc.c | 12 +- tools/nitroarc/src/common.h | 15 +-- tools/nitroarc/src/main.c | 40 ++++--- tools/nitroarc/src/opmode_create.c | 164 ++++++++++++++++++++------ tools/nitroarc/src/opmode_extract.c | 2 +- tools/nitroarc/src/opmode_list.c | 7 +- tools/nitroarc/src/opmode_metadata.c | 2 +- 9 files changed, 225 insertions(+), 82 deletions(-) diff --git a/tools/nitroarc/doc/nitroarc.1.adoc b/tools/nitroarc/doc/nitroarc.1.adoc index bfd4cf511b..af8e1a48a8 100644 --- a/tools/nitroarc/doc/nitroarc.1.adoc +++ b/tools/nitroarc/doc/nitroarc.1.adoc @@ -32,7 +32,14 @@ one of the following flags: *-c, --create*:: Create _ARCHIVE_ with the files in _DIRECTORY_. All files which descend from - _DIRECTORY_ or any of its subdirectories will be included in _ARCHIVE_. + _DIRECTORY_ or any of its subdirectories will be included in _ARCHIVE_. By + default, all files which match either of the patterns “.\*ignore” or + “.\*order” will be ignored. If a file named “.narcorder” is present in + _DIRECTORY_, then it will be automatically loaded as if it had been given as + an argument to the *-T* option. If a file named “.narcignore” is present in + _DIRECTORY_, then it will be automatically loaded as if it had been given as + an argument to the *-X* option. In either case, a file given as an explicit + option-argument will take precedence. *-m, --meta, --metadata*:: View tabulated metadata about the sections of _ARCHIVE_. @@ -94,16 +101,13 @@ evaluated. option. *-I, --index*:: - Output a C header for _ARCHIVE_ to a file-path mirroring _ARCHIVE_ with its - extension replaced by “.naix”. C programs may use this header to map relative - paths from the local filesystem to their indices in _ARCHIVE_ via preprocessor - “#define” statements. Any character in the local path for a member file which - is neither an alphanumeric ASCII character nor an ASCII underscore (‘_’) will - be replaced by an ASCII underscore in the respective preprocessor token. e.g., - a member file located at “/path/to/file” will write “#define path_to_file”, - followed by a single ASCII space (‘ ’) and its member index on the same line. - If a member file is included in the archive multiple times, then occurrences - past the first will be suffixed with the number of previous occurrences. + Output information about the constructed _ARCHIVE_ as sibling files. For full + details, see **The Index Files**. + +*-P, --index-namespace*:: + Identical to *--index*, but all output preprocessor definitions are prefixed + with a namespace of “NARC_” and the name of the output archive, minus its + extension. *-N, --named*:: Mirror the local filesystem from _DIRECTORY_ in _ARCHIVE_, with _DIRECTORY_ @@ -132,6 +136,31 @@ evaluated. included between the header cells and the first row of data cells; such output may thus be evaluated as a sequence of pipe-delimited rows. +=== The Index Files === + +Two additional sibling files are produced alongside the output _ARCHIVE_ when +the *--index* option is given: a C header (suffixed as `.naix`) and a record +table (suffixed as `.recs`) containing information about the packing run. + +All file-paths ingested from the packing directory are transformed into +identifiers by transforming all characters which are neither an alphanumeric +ASCII character into an ASCII underscore (‘_’). e.g., a member file located at +“path/to/file” will be mapped to “path_to_file”. If such an identifier is +already registered, then a suffix of “_1” is appended, incrementing the suffix +with each occurrence. The generated identifier is used in both the C header and +the record table. + +The C header writes “#define IDENTIFIER INDEX” for each member of the archive, +where _IDENTIFIER_ is the generated identifier as above and _INDEX_ is the +positional index of the file in the archive. + +The record table writes in a machine-friendly format. Individual records within +the file are separated by the ASCII record-separator (_0x1E_), and fields within +each record are separated by the ASCII unit-separator (_0x1F_). The first record +of the table contains a single field: _DIRECTORY_ from the command arguments. +Each record thereafter contains two fields: the relative path of the member file +from _DIRECTORY_, then _IDENTIFIER_ as above. + Exit Status ----------- diff --git a/tools/nitroarc/lib/include/nitroarc.h b/tools/nitroarc/lib/include/nitroarc.h index 07c1e050a9..9e3302a8c8 100644 --- a/tools/nitroarc/lib/include/nitroarc.h +++ b/tools/nitroarc/lib/include/nitroarc.h @@ -26,6 +26,16 @@ extern "C" { #include #include +#define NITROARC_VERSION_MAJOR 1 +#define NITROARC_VERSION_MINOR 1 +#define NITROARC_VERSION_PATCH 0 + +static inline int nitroarc_version(void) { + return (NITROARC_VERSION_MAJOR << 16) + | (NITROARC_VERSION_MINOR << 8) + | (NITROARC_VERSION_PATCH); +} + typedef struct nitroarc_fatb nitroarc_fatb_t; struct nitroarc_fatb { uint32_t ofs_head; @@ -57,7 +67,9 @@ typedef struct nitroarc nitroarc_t; struct nitroarc { uint32_t size; uint16_t nfiles; - uint16_t ndirs; + uint16_t ndirs : 12; // Maximum number of directories is 4096 + uint16_t named : 1; + uint16_t reserved : 3; const void *head; nitroarc_fatb_t fatb; diff --git a/tools/nitroarc/lib/nitroarc.c b/tools/nitroarc/lib/nitroarc.c index 0587b6c502..c952457330 100644 --- a/tools/nitroarc/lib/nitroarc.c +++ b/tools/nitroarc/lib/nitroarc.c @@ -258,7 +258,7 @@ int nitroarc_nameof(const nitroarc_t *narc, uint16_t i, char *buf, size_t size) assert(buf); assert(size); - if (narc->ndirs == 1) { + if (!narc->named) { *buf = 0; return NITROARC_ESUCCESS; } @@ -266,9 +266,7 @@ int nitroarc_nameof(const nitroarc_t *narc, uint16_t i, char *buf, size_t size) if ((i & FNTB_FILESYS_MASKTYPE)) return NITROARC_EINDEXDIR; if (narc->nfiles <= i) return NITROARC_EINDEXRANGE; - char *p_buf = buf; - *p_buf++ = '/'; - + char *p_buf = buf; const char *p_fntb = narc->fntb.data; const char *p_dirtab = p_fntb; const char *p_enttab = p_fntb + leu32(p_dirtab); @@ -1007,13 +1005,14 @@ static int nitroarc_fntb(nitroarc_t *narc, int64_t *running_size) { *running_size -= size; if (*running_size < 0) return NITROARC_EFNTBSIZE; + narc->named = size > FNTB_HEADERSIZE + FNTB_DIRTAB_ENTRYSIZE; narc->fntb.size = size; narc->fntb.data = head + FNTB_HEADERSIZE; // First entry pointer narc->fimg.data = head + narc->fntb.size; // Head of next section narc->fntb.ofs_head = (uint32_t)ptrdiff(head, narc->head); narc->fntb.ofs_data = (uint32_t)ptrdiff(narc->fntb.data, narc->head); - narc->ndirs = leu16(&((uint8_t *)narc->fntb.data)[0x06]); + narc->ndirs = (uint16_t)(leu16(&((uint8_t *)narc->fntb.data)[0x06]) & 0xFFF); return NITROARC_ESUCCESS; } @@ -1055,11 +1054,12 @@ static int read_stripped(const uint8_t *data, uint32_t size, nitroarc_t *narc) { narc->fatb.ofs_data = fatb_offs; narc->nfiles = (uint16_t)(fatb_size / FATB_ENTRYSIZE); + narc->named = fntb_size == FNTB_DIRTAB_ENTRYSIZE; narc->fntb.size = fntb_size; narc->fntb.data = data + fntb_offs; narc->fntb.ofs_head = 0x00; narc->fntb.ofs_data = fntb_offs; - narc->ndirs = leu16(&((uint8_t *)narc->fntb.data)[0x06]); + narc->ndirs = (uint16_t)(leu16(&((uint8_t *)narc->fntb.data)[0x06]) & 0xFFF); narc->fimg.size = size - fntb_size - fatb_size - 0x10; narc->fimg.data = data; // all FATB offsets in stripped variant are absolute diff --git a/tools/nitroarc/src/common.h b/tools/nitroarc/src/common.h index 345b1a95b8..6e4d8200e9 100644 --- a/tools/nitroarc/src/common.h +++ b/tools/nitroarc/src/common.h @@ -46,12 +46,13 @@ struct options { unsigned int mode : 4; // operation mode unsigned int verbose : 1; // -v, --verbose unsigned int help : 1; // -?, --help - unsigned int version : 1; // --version - unsigned int no_header : 1; // --no-header - unsigned int index : 1; // -N, --index - unsigned int no_recurse : 1; // --no-recursion - unsigned int named : 1; // --named - unsigned int stripped : 1; // --stripped + unsigned int version : 1; // -V, --version + unsigned int no_header : 1; // -H, --no-header + unsigned int index : 1; // -I, --index + unsigned int index_ns : 1; // -P, --index-namespace + unsigned int no_recurse : 1; // -R, --no-recursion + unsigned int named : 1; // -N, --named + unsigned int stripped : 1; // -S, --stripped int argc; const char **argv; @@ -59,8 +60,8 @@ struct options { const char *directory; // -C, --directory=DIR const char *file; // -f, --file=ARCHIVE + const char *single_file; // -O, --single-file=FILE const char *format; // -F, --format=FORMAT - const char *single_file; // -O --single-file=FILE const char *files_from; // -T, --files-from=FILE const char *exclude_from; // -X, --exclude-from=FILE const char *exclude_pat; // --exclude=PATTERN diff --git a/tools/nitroarc/src/main.c b/tools/nitroarc/src/main.c index 0a50da1154..99bcdcbd57 100644 --- a/tools/nitroarc/src/main.c +++ b/tools/nitroarc/src/main.c @@ -22,6 +22,7 @@ #include #include "common.h" +#include "nitroarc.h" #include "optparse.h" enum { @@ -92,6 +93,7 @@ enum { single_file, files_from, index, + index_namespace, no_recurse, named, stripped, @@ -113,14 +115,15 @@ static const option_cfg_t s_options[] = { [format] = { "format", NULL, 'F', 0, true }, [no_header] = { "no-header", NULL, 'H', 0, false }, - [exclude] = { "exclude", NULL, 'E', 0, true }, - [exclude_from] = { "exclude-from", NULL, 'X', 0, true }, - [single_file] = { "single-file", NULL, 'O', 0, true }, - [files_from] = { "files-from", NULL, 'T', 0, true }, - [index] = { "index", NULL, 'I', 0, false }, - [no_recurse] = { "no-recursion", NULL, 'R', 0, false }, - [named] = { "named", NULL, 'N', 0, false }, - [stripped] = { "stripped", NULL, 'S', 0, false }, + [exclude] = { "exclude", NULL, 'E', 0, true }, + [exclude_from] = { "exclude-from", NULL, 'X', 0, true }, + [single_file] = { "single-file", NULL, 'O', 0, true }, + [files_from] = { "files-from", NULL, 'T', 0, true }, + [index] = { "index", NULL, 'I', 0, false }, + [index_namespace] = { "index-namespace", NULL, 'P', 0, false }, + [no_recurse] = { "no-recursion", NULL, 'R', 0, false }, + [named] = { "named", NULL, 'N', 0, false }, + [stripped] = { "stripped", NULL, 'S', 0, false }, [help] = { "help", NULL, '?', 'h', false }, [version] = { "version", NULL, 'V', 0, false }, @@ -171,12 +174,13 @@ int parse_opts(const char **argv, options_t *opts) { case exclude_from: target_optarg(opts->exclude_from); case exclude: target_optarg(opts->exclude_pat); - case verbose: opts->verbose = true; break; - case no_header: opts->no_header = true; break; - case index: opts->index = true; break; - case no_recurse: opts->no_recurse = true; break; - case named: opts->named = true; break; - case stripped: opts->stripped = true; break; + case verbose: opts->verbose = true; break; + case no_header: opts->no_header = true; break; + case index: opts->index = true; break; + case index_namespace: opts->index = true; opts->index_ns = true; break; + case no_recurse: opts->no_recurse = true; break; + case named: opts->named = true; break; + case stripped: opts->stripped = true; break; case OPT_ERROR: progerr("%s", parser.errmsg); @@ -220,6 +224,7 @@ static void exit_help(const char *name, int exit_status) { puts(" -X, --exclude-from=FILE read exclusion patterns from FILE"); puts(" -T, --files-from=FILE read ordered filenames from FILE"); puts(" -I, --index create a C-header index of member files"); + puts(" -P, --index-namespace like --index, with namespace-prefixes"); puts(" -N, --named retain filenames in the archive"); puts(" -R, --no-recursion do not discover files in subdirectories"); puts(" -O, --single-file=FILE specify FILE as the only member file"); @@ -242,7 +247,12 @@ static void exit_help(const char *name, int exit_status) { } static void exit_version(void) { - puts("nitroarc v0.0.1"); + putf( + "nitroarc v%d.%d.%d\n", + NITROARC_VERSION_MAJOR, + NITROARC_VERSION_MINOR, + NITROARC_VERSION_PATCH + ); puts(""); puts("Copyright (C) 2026 Rachel "); puts(""); diff --git a/tools/nitroarc/src/opmode_create.c b/tools/nitroarc/src/opmode_create.c index af14f5cf1a..1e720e39cf 100644 --- a/tools/nitroarc/src/opmode_create.c +++ b/tools/nitroarc/src/opmode_create.c @@ -29,8 +29,8 @@ #include #include -#include "nitroarc.h" #include "common.h" +#include "nitroarc.h" typedef struct dirent dirent_t; typedef struct stat stat_t; @@ -49,11 +49,15 @@ struct packcfg { bool stripped; }; +static int peek_dotfiles(options_t *opts); static int prepare_exclusions(const char *fdata, const char *pat, strvec_t *out_excls); static int collect_explicit_files(const char *fdata, packcfg_t *out_cfg); static int collect_implicit_files(strvec_t *files, const strvec_t *excls, size_t *out_nexpls); static int pack_archive(packcfg_t *cfg, void **out_data, size_t *out_size); -static int write_index(const char *fname, bool index, const strvec_t *files); +static int write_index(const char *fname, bool index, bool namespace, const strvec_t *files, const char *indir); + +#define HIT_DOTORDER (1 << 0) +#define HIT_DOTIGNORE (1 << 1) extern int tool_create(const options_t *opts) { if (opts->file == NULL) { @@ -87,6 +91,7 @@ extern int tool_create(const options_t *opts) { .stripped = opts->stripped, }; + int dots = peek_dotfiles((options_t *)opts); strvec_t excls = { 0 }; char *ogcwd = getcwd(NULL, 0); char *f_incl = (char *)opts->single_file; @@ -105,20 +110,77 @@ extern int tool_create(const options_t *opts) { || pack_archive(&cfg, (void **)&data, &size) || set_workdir(ogcwd) || write_file(opts->file, data, size) - || write_index(opts->file, opts->index, &cfg.files) + || write_index(opts->file, opts->index, opts->index_ns, &cfg.files, opts->argv[0]) || EXIT_SUCCESS; for (size_t i = nexpls; i < cfg.files.size; i++) free(cfg.files.data[i]); free(cfg.files.data); free(excls.data); // none are internally-owned free(ogcwd); - if (opts->files_from) - free(f_incl); + if (opts->files_from) free(f_incl); free(f_excl); free(data); + + if (dots & HIT_DOTORDER) free((char *)opts->files_from); + if (dots & HIT_DOTIGNORE) free((char *)opts->exclude_from); + return errc; } +static char* join_paths(const char *parent, const char *entry) { + size_t size_p = parent ? strlen(parent) + 1 : 0; + size_t size_e = strlen(entry); + + char *path = malloc(size_p + size_e + 1); + if (path != NULL) { + if (size_p) { + memcpy(path, parent, size_p - 1); + path[size_p - 1] = '/'; + } + + memcpy(path + size_p, entry, size_e); + path[size_p + size_e] = 0; + } + + return path; +} + +static int peek_dotfiles(options_t *opts) { + char *order = join_paths(opts->argv[0], ".narcorder"); + char *ignore = join_paths(opts->argv[0], ".narcignore"); + int hits = 0; + stat_t stbuf = { 0 }; + + if (stat(order, &stbuf) == 0) { + if (opts->files_from != NULL) { + progerr("'--files-from' given as %s; skipping .narcorder", opts->files_from); + free(order); + } + else { + proglog("reading implicit inclusions from %s", order); + opts->files_from = order; + + hits |= HIT_DOTORDER; + } + } + + if (stat(ignore, &stbuf) == 0) { + if (opts->exclude_from != NULL) { + progerr("'--exclude-from' given as %s; skipping .narcignore", opts->exclude_from); + free(ignore); + } + else { + proglog("reading implicit exclusions from %s", ignore); + opts->exclude_from = ignore; + + hits |= HIT_DOTIGNORE; + } + } + + errno = 0; + return hits; +} + static size_t strvec_nhits(const strvec_t *vec, char *s, size_t max_i); static bool strvec_has(const strvec_t *vec, char *s); static int strvec_grow(strvec_t *vec); @@ -168,6 +230,9 @@ static int prepare_exclusions( out_excls->data = malloc(out_excls->cap * sizeof(*out_excls->data)); if (out_excls->data == NULL) goto erralloc; + strvec_push(out_excls, ".*ignore"); + strvec_push(out_excls, ".*keep"); + strvec_push(out_excls, ".*order"); if (pat != NULL) strvec_push(out_excls, (char *)pat); if (fdata == NULL) goto done; @@ -253,24 +318,6 @@ static bool should_exclude(const char *name, const strvec_t *excls) { return false; } -static char* join_paths(const char *parent, const char *entry) { - size_t size_p = parent ? strlen(parent) + 1 : 0; - size_t size_e = strlen(entry); - - char *path = malloc(size_p + size_e + 1); - if (path != NULL) { - if (size_p) { - memcpy(path, parent, size_p - 1); - path[size_p - 1] = '/'; - } - - memcpy(path + size_p, entry, size_e); - path[size_p + size_e] = 0; - } - - return path; -} - static int collect_implicit_files(strvec_t *files, const strvec_t *excls, size_t *out_nexpls) { assert(files); assert(files->data); @@ -491,26 +538,53 @@ static char* guardify_nhits(const char *name, size_t size, size_t nhits) { return suffixed; } -static int write_index(const char *fname, bool index, const strvec_t *files) { +#define ASCII_SEP_RECORD 0x1E +#define ASCII_SEP_UNIT 0x1F + +static int write_index( + const char *fname, + bool index, + bool namespace, + const strvec_t *files, + const char *indir +) { assert(fname); assert(files); assert(files->data); if (!index) return PROGRAM_ENONE; - char *guard = NULL; - FILE *fnaix = NULL; - char *pdot = strrstem(fname, '.'); - size_t size = pdot - fname; - char *name = malloc(size + 6); - if (name == NULL) goto erralloc; + char *guard = NULL; + FILE *fnaix = NULL; + FILE *frecs = NULL; + char *pdot = strrstem(fname, '.'); + char *psep = strrstem(fname, '/'); + psep += *psep == '/'; - memcpy(name, fname, size); - memcpy(name + size, ".naix", 6); - guard = guardify(name, size + 5); + size_t size = pdot - fname; + char *bname = malloc(pdot - psep + 2); + char *iname = malloc(size + 6); + char *rname = malloc(size + 6); + if (bname == NULL) goto erralloc; + if (iname == NULL) goto erralloc; + if (rname == NULL) goto erralloc; + + memcpy(bname, psep, pdot - psep); + bname[pdot - psep] = '_'; + bname[pdot - psep + 1] = 0; + + memcpy(iname, fname, size); + memcpy(iname + size, ".naix", 6); + guard = guardify(iname, size + 5); if (guard == NULL) goto erralloc; - int errc = open_file(name, "wb", &fnaix); + memcpy(rname, fname, size); + memcpy(rname + size, ".recs", 6); + + int errc = open_file(iname, "wb", &fnaix); + if (errc) goto cleanup; + + errc = open_file(rname, "wb", &frecs); if (errc) goto cleanup; fprintf(fnaix, "/*\n"); @@ -522,12 +596,25 @@ static int write_index(const char *fname, bool index, const strvec_t *files) { fprintf(fnaix, "#define %s\n", guard); fprintf(fnaix, "\n"); + fprintf(frecs, "%s%c", indir, ASCII_SEP_RECORD); + for (size_t i = 0; i < files->size; i++) { size_t nhits = strvec_nhits(files, files->data[i], i); char *defn = guardify_nhits(files->data[i], strlen(files->data[i]), nhits); if (defn == NULL) { free(defn); goto erralloc; } - fprintf(fnaix, "#define %s %zu\n", defn, i); + fprintf(fnaix, "#define %s%s%s %zu\n", + namespace ? "NARC_" : "", + namespace ? bname : "", // TODO: add the name of the NARC, minus the extension + defn, + i); + fprintf(frecs, "%s%c%s%s%s%c", + files->data[i], + ASCII_SEP_UNIT, + namespace ? "NARC_" : "", + namespace ? bname : "", // TODO: add the name of the NARC, minus the extension + defn, + ASCII_SEP_RECORD); free(defn); } @@ -544,7 +631,12 @@ erralloc: errc = PROGRAM_EALLOC; cleanup: - free(name); + if (fnaix) fclose(fnaix); + if (frecs) fclose(frecs); + + free(rname); + free(bname); + free(iname); free(guard); return errc; } diff --git a/tools/nitroarc/src/opmode_extract.c b/tools/nitroarc/src/opmode_extract.c index 4109f7397e..8b9c7c071d 100644 --- a/tools/nitroarc/src/opmode_extract.c +++ b/tools/nitroarc/src/opmode_extract.c @@ -25,9 +25,9 @@ #include #include -#include "nitroarc.h" #include "common.h" #include "extensions.h" +#include "nitroarc.h" static int deduce_outdir(const options_t *opts, char **out_dirname); static int extract_members(const nitroarc_t *narc, const char *outdir); diff --git a/tools/nitroarc/src/opmode_list.c b/tools/nitroarc/src/opmode_list.c index 6db961e58e..1d8c9a23a4 100644 --- a/tools/nitroarc/src/opmode_list.c +++ b/tools/nitroarc/src/opmode_list.c @@ -23,9 +23,9 @@ #include #include -#include "nitroarc.h" #include "common.h" #include "extensions.h" +#include "nitroarc.h" static int print_members(nitroarc_t *narc, const char *format, bool header); @@ -65,8 +65,7 @@ static const fmtfunc_t handlers[] = { }; static int print_members(nitroarc_t *narc, const char *format, bool header) { - bool named = narc->ndirs > 1; - if (format == NULL) return print_members_markdown(narc, header, named); + if (format == NULL) return print_members_markdown(narc, header, narc->named); const fmtfunc_t *candidate = &handlers[0]; while (candidate->func != NULL) { @@ -79,7 +78,7 @@ static int print_members(nitroarc_t *narc, const char *format, bool header) { return PROGRAM_EGENERAL; } - return candidate->func(narc, header, named); + return candidate->func(narc, header, narc->named); } static inline ptrdiff_t ptrdiff(const void *_l, const void *_r) { diff --git a/tools/nitroarc/src/opmode_metadata.c b/tools/nitroarc/src/opmode_metadata.c index 7e5d983407..03a69501da 100644 --- a/tools/nitroarc/src/opmode_metadata.c +++ b/tools/nitroarc/src/opmode_metadata.c @@ -21,8 +21,8 @@ #include #include -#include "nitroarc.h" #include "common.h" +#include "nitroarc.h" static int print_metadata(const nitroarc_t *narc, const options_t *opts);