diff options
| author | ruki <[email protected]> | 2026-03-30 21:58:26 +0800 |
|---|---|---|
| committer | GitHub <[email protected]> | 2026-03-30 21:58:26 +0800 |
| commit | 4222dfcc1e73ec1f6fbe399ff1de6fb52e17af1e (patch) | |
| tree | b46f1bda336f1a56a2804a06108649f032eb4a00 | |
| parent | 01c2251b193482d9f308c92c27bb113c77dd60b4 (diff) | |
| parent | 53748c3a92f9f6c11453ed2f3a9af761275e732a (diff) | |
Merge pull request #7440 from xmake-io/comments
Improve comments
77 files changed, 1527 insertions, 217 deletions
diff --git a/xmake/core/base/bloom_filter.lua b/xmake/core/base/bloom_filter.lua index d82618be9..31f61bdf9 100644 --- a/xmake/core/base/bloom_filter.lua +++ b/xmake/core/base/bloom_filter.lua @@ -54,12 +54,18 @@ function _instance.new(handle) return instance end --- get cdata of the bloom filter +-- get the internal cdata handle +-- +-- @return the cdata +-- function _instance:cdata() return self._HANDLE end --- get the bloom filter data +-- get serialized bloom filter data +-- +-- @return the data bytes, or nil and error info +-- function _instance:data() -- ensure opened local ok, errors = self:_ensure_opened() @@ -78,7 +84,11 @@ function _instance:data() return bytes(size, data) end --- set the bloom filter data +-- load bloom filter from serialized data +-- +-- @param data the data bytes +-- @return true on success, or false and error info +-- function _instance:data_set(data) -- ensure opened local ok, errors = self:_ensure_opened() @@ -95,7 +105,10 @@ function _instance:data_set(data) return bloom_filter._data_set(self:cdata(), dataaddr, datasize) end --- clear the bloom filter data +-- clear all data in the bloom filter +-- +-- @return true on success, or false and error info +-- function _instance:clear() -- ensure opened local ok, errors = self:_ensure_opened() diff --git a/xmake/core/base/coroutine.lua b/xmake/core/base/coroutine.lua index 2ed91c354..2335f29d8 100644 --- a/xmake/core/base/coroutine.lua +++ b/xmake/core/base/coroutine.lua @@ -29,7 +29,12 @@ local string = require("base/string") -- save original interfaces coroutine._resume = coroutine._resume or coroutine.resume --- resume coroutine +-- resume coroutine with enhanced error reporting +-- +-- @param co the coroutine to resume +-- @param ... the resume arguments +-- @return true and results on success, or false and error info +-- function coroutine.resume(co, ...) local ok, results = coroutine._resume(co, ...) if not ok then diff --git a/xmake/core/base/debugger.lua b/xmake/core/base/debugger.lua index f62871482..f9a5e451e 100644 --- a/xmake/core/base/debugger.lua +++ b/xmake/core/base/debugger.lua @@ -47,14 +47,17 @@ function debugger:_start_emmylua_debugger() return true end --- start debugging +-- start the debugger (attach to IDE) function debugger:start() if self:has_emmylua() then return self:_start_emmylua_debugger() end end --- has emmylua debugger? +-- has EmmyLua debugger available? +-- +-- @return true if available +-- function debugger:has_emmylua() local debugger_libfile = os.getenv("EMMYLUA_DEBUGGER") if debugger_libfile and os.isfile(debugger_libfile) then @@ -62,7 +65,10 @@ function debugger:has_emmylua() end end --- debugger is enabled? +-- is the debugger enabled? +-- +-- @return true if enabled via --debugger option +-- function debugger:enabled() return self:has_emmylua() end diff --git a/xmake/core/base/filter.lua b/xmake/core/base/filter.lua index dae397e4e..0312c4fa5 100644 --- a/xmake/core/base/filter.lua +++ b/xmake/core/base/filter.lua @@ -33,7 +33,10 @@ local scheduler = require("base/scheduler") local escape_table1 = {["$"] = "\001", ["("] = "\002", [")"] = "\003", ["%"] = "\004"} local escape_table2 = {["\001"] = "$", ["\002"] = "(", ["\003"] = ")", ["\004"] = "%"} --- new filter instance +-- create a new filter instance for variable substitution +-- +-- @return the filter instance +-- function filter.new() -- init an filter instance @@ -51,7 +54,10 @@ end -- e.g. -- -- print("$(shell echo hello xmake)") --- add_ldflags("$(shell pkg-config --libs sqlite3)") +-- execute shell command and return output for $(shell ...) substitution +-- +-- @param cmd the shell command +-- @return the command output string -- function filter.shell(cmd) @@ -77,12 +83,20 @@ function filter.shell(cmd) return outdata end --- filter the environment variables +-- get environment variable value for $(env ...) substitution +-- +-- @param name the environment variable name +-- @return the environment value +-- function filter.env(name) return os.getenv(name) end --- filter the winreg path +-- query windows registry value for $(reg ...) substitution +-- +-- @param path the registry path +-- @return the registry value +-- function filter.reg(path) -- must be windows diff --git a/xmake/core/base/libc.lua b/xmake/core/base/libc.lua index f9a12931e..b72c77ce4 100644 --- a/xmake/core/base/libc.lua +++ b/xmake/core/base/libc.lua @@ -44,6 +44,12 @@ if ffi then ]] end +-- allocate memory +-- +-- @param size the memory size in bytes +-- @param opt the options, e.g. {zeroed = true} +-- @return the cdata pointer +-- function libc.malloc(size, opt) if ffi then if opt and opt.gc then @@ -60,6 +66,10 @@ function libc.malloc(size, opt) end end +-- free memory +-- +-- @param data the cdata pointer to free +-- function libc.free(data) if ffi then return ffi.C.free(data) @@ -68,6 +78,12 @@ function libc.free(data) end end +-- copy memory +-- +-- @param dst the destination pointer +-- @param src the source pointer +-- @param size the copy size in bytes +-- function libc.memcpy(dst, src, size) if ffi then return ffi.copy(dst, src, size) @@ -76,6 +92,12 @@ function libc.memcpy(dst, src, size) end end +-- move memory (handles overlapping regions) +-- +-- @param dst the destination pointer +-- @param src the source pointer +-- @param size the move size in bytes +-- function libc.memmov(dst, src, size) if ffi then return ffi.C.memmove(dst, src, size) @@ -84,6 +106,12 @@ function libc.memmov(dst, src, size) end end +-- fill memory with a byte value +-- +-- @param data the memory pointer +-- @param ch the byte value +-- @param size the fill size in bytes +-- function libc.memset(data, ch, size) if ffi then return ffi.fill(data, size, ch) @@ -92,6 +120,12 @@ function libc.memset(data, ch, size) end end +-- duplicate a string with length limit +-- +-- @param s the source string +-- @param n the maximum length +-- @return the new cdata string pointer +-- function libc.strndup(s, n) if ffi then return ffi.string(s, n) @@ -104,6 +138,12 @@ function libc.strndup(s, n) end end +-- get byte value at the given offset +-- +-- @param data the memory pointer +-- @param offset the byte offset +-- @return the byte value +-- function libc.byteof(data, offset) if ffi then return data[offset] @@ -112,6 +152,12 @@ function libc.byteof(data, offset) end end +-- set byte value at the given offset +-- +-- @param data the memory pointer +-- @param offset the byte offset +-- @param value the byte value +-- function libc.setbyte(data, offset, value) if ffi then data[offset] = value @@ -120,6 +166,12 @@ function libc.setbyte(data, offset, value) end end +-- get cdata pointer from string or bytes +-- +-- @param data the string or bytes data +-- @param opt the options (optional) +-- @return the cdata pointer +-- function libc.dataptr(data, opt) opt = opt or {} if ffi and opt.ffi ~= false then @@ -133,6 +185,12 @@ function libc.dataptr(data, opt) end end +-- get the numeric address of a cdata pointer +-- +-- @param data the cdata pointer +-- @param opt the options (optional) +-- @return the address as number +-- function libc.ptraddr(data, opt) opt = opt or {} if ffi and opt.ffi ~= false then diff --git a/xmake/core/base/list.lua b/xmake/core/base/list.lua index 671d17be8..4caed81bc 100644 --- a/xmake/core/base/list.lua +++ b/xmake/core/base/list.lua @@ -24,7 +24,7 @@ local object = require("base/object") -- define module local list = list or object { _init = {"_length"} } {0} --- clear list +-- clear all elements function list:clear() self._length = 0 self._first = nil @@ -136,37 +136,59 @@ function list:remove_last() return t end --- push item to tail +-- push element to the back +-- +-- @param t the element +-- function list:push(t) self:insert_last(t) end --- pop item from tail +-- pop element from the back +-- +-- @return the removed element +-- function list:pop() self:remove_last() end --- shift item: 1 2 3 <- 2 3 +-- shift element from the front +-- +-- @return the removed element +-- function list:shift() self:remove_first() end --- unshift item: 1 2 -> t 1 2 +-- unshift element to the front +-- +-- @param t the element +-- function list:unshift(t) self:insert_first(t) end --- get first item +-- get the first element +-- +-- @return the first element, or nil if empty +-- function list:first() return self._first end --- get last item +-- get the last element +-- +-- @return the last element, or nil if empty +-- function list:last() return self._last end --- get next item +-- get the next element after the given one +-- +-- @param last the current element +-- @return the next element, or nil +-- function list:next(last) if last then return last._next @@ -175,7 +197,11 @@ function list:next(last) end end --- get the previous item +-- get the previous element before the given one +-- +-- @param last the current element +-- @return the previous element, or nil +-- function list:prev(last) if last then return last._prev @@ -184,12 +210,18 @@ function list:prev(last) end end --- get list size +-- get the list size +-- +-- @return the number of elements +-- function list:size() return self._length end --- is empty? +-- is the list empty? +-- +-- @return true if empty +-- function list:empty() return self:size() == 0 end @@ -202,6 +234,10 @@ end -- print(item) -- end -- +-- iterate elements from front to back +-- +-- @return the iterator function +-- function list:items() local iter = function (list, item) return list:next(item) @@ -209,7 +245,10 @@ function list:items() return iter, self, nil end --- get reverse items +-- iterate elements from back to front +-- +-- @return the reverse iterator function +-- function list:ritems() local iter = function (list, item) return list:prev(item) diff --git a/xmake/core/base/log.lua b/xmake/core/base/log.lua index 405002286..7995c8b38 100644 --- a/xmake/core/base/log.lua +++ b/xmake/core/base/log.lua @@ -21,7 +21,10 @@ -- define module: log local log = log or {} --- get the log file +-- get the log file object +-- +-- @return the file object +-- function log:file() -- disable? @@ -56,7 +59,10 @@ function log:file() return self._FILE end --- get the output file +-- get the output log file path +-- +-- @return the log file path +-- function log:outputfile() if self._LOGFILE == nil then self._LOGFILE = os.getenv("XMAKE_LOGFILE") or false @@ -64,19 +70,22 @@ function log:outputfile() return self._LOGFILE end --- clear log +-- clear the log file function log:clear(state) if os.isfile(self:outputfile()) then io.writefile(self:outputfile(), "") end end --- enable log +-- enable or disable logging +-- +-- @param state true to enable, false to disable +-- function log:enable(state) self._ENABLE = state end --- flush log to file +-- flush log buffer to file function log:flush() local file = self:file() if file then @@ -92,7 +101,10 @@ function log:close() end end --- print log to the log file +-- print log with newline to the log file +-- +-- @param ... the format string and arguments +-- function log:print(...) local file = self:file() if file then @@ -100,7 +112,10 @@ function log:print(...) end end --- print variables to the log file +-- print variables to the log file (verbose mode only) +-- +-- @param ... the variables to print +-- function log:printv(...) local file = self:file() if file then @@ -120,7 +135,10 @@ function log:printv(...) end end --- printf log to the log file +-- printf log without newline to the log file +-- +-- @param ... the format string and arguments +-- function log:printf(...) local file = self:file() if file then @@ -128,7 +146,10 @@ function log:printf(...) end end --- write log the log file +-- write raw data to the log file +-- +-- @param ... the data to write +-- function log:write(...) local file = self:file() if file then diff --git a/xmake/core/base/option.lua b/xmake/core/base/option.lua index 6d46bddef..decb1e842 100644 --- a/xmake/core/base/option.lua +++ b/xmake/core/base/option.lua @@ -65,7 +65,11 @@ function option._context() end end --- save context +-- save option context (push a new context onto the stack) +-- +-- @param taskname the task name (optional) +-- @return the new context +-- function option.save(taskname) option._CONTEXTS = option._CONTEXTS or {} local context = {options = {}, defaults = {}, taskname = taskname} @@ -76,7 +80,7 @@ function option.save(taskname) return context end --- restore context +-- restore option context (pop the current context from the stack) function option.restore() if option._CONTEXTS then table.remove(option._CONTEXTS) @@ -142,7 +146,13 @@ function option.init(menu) return true end --- parse arguments with the given options +-- parse arguments with the given options definition +-- +-- @param argv the arguments array or string +-- @param options the options definition table +-- @param opt the description and usage strings +-- @return the parsed options table +-- function option.parse(argv, options, opt) assert(argv and options) opt = opt or { populate_defaults = true } @@ -306,6 +316,9 @@ end -- get the current task name +-- +-- @return the task name string +-- function option.taskname() return option._context().taskname end @@ -324,6 +337,10 @@ function option.taskmenu(task) end -- get the given option value for the current task +-- +-- @param name the option name, e.g. "verbose", "diagnosis", "target" +-- @return the option value +-- function option.get(name) local options = option.options() if options then @@ -336,6 +353,10 @@ function option.get(name) end -- set the given option for the current task +-- +-- @param name the option name +-- @param value the option value +-- function option.set(name, value) -- cannot be the first context for menu assert(#option._CONTEXTS > 1) @@ -348,7 +369,11 @@ function option.set(name, value) options[name] = value end --- get the boolean value +-- convert value to boolean (handles "y", "yes", "true", etc.) +-- +-- @param value the value to convert +-- @return true, false, or nil +-- function option.boolean(value) if type(value) == "string" then local v = value:lower() @@ -359,7 +384,11 @@ function option.boolean(value) return value end --- get the given default option value for the current task +-- get the default option value for the current task +-- +-- @param name the option name +-- @return the default value +-- function option.default(name) assert(name) diff --git a/xmake/core/base/pipe.lua b/xmake/core/base/pipe.lua index 4b122ed9e..137f9c779 100644 --- a/xmake/core/base/pipe.lua +++ b/xmake/core/base/pipe.lua @@ -59,6 +59,11 @@ function _instance:cdata() end -- write data to pipe file +-- +-- @param data the data to write (string or bytes) +-- @param opt the options, e.g. {block = true} +-- @return the real written size, or -1 and error info +-- function _instance:write(data, opt) -- ensure opened @@ -119,6 +124,12 @@ function _instance:write(data, opt) end -- read data from pipe +-- +-- @param buff the buffer to receive data +-- @param size the read size +-- @param opt the options, e.g. {block = true} +-- @return the real read size, or -1 and error info +-- function _instance:read(buff, size, opt) assert(buff) @@ -187,6 +198,10 @@ function _instance:read(buff, size, opt) end -- connect pipe, only for named pipe (server-side) +-- +-- @param opt the options +-- @return true on success +-- function _instance:connect(opt) -- ensure opened @@ -218,6 +233,11 @@ function _instance:connect(opt) end -- wait pipe events +-- +-- @param events the events to wait, e.g. pipe.EV_READ, pipe.EV_WRITE +-- @param timeout the timeout in milliseconds, -1 for infinite +-- @return the received events, or 0 on timeout +-- function _instance:wait(events, timeout) -- ensure opened @@ -241,6 +261,9 @@ function _instance:wait(events, timeout) end -- close pipe file +-- +-- @return true on success +-- function _instance:close() -- ensure opened diff --git a/xmake/core/base/poller.lua b/xmake/core/base/poller.lua index b989af8a9..bb18dfda4 100644 --- a/xmake/core/base/poller.lua +++ b/xmake/core/base/poller.lua @@ -56,17 +56,27 @@ function poller:_pollerdata_set(cdata, data) pollerdata[cdata] = data end --- support events? +-- check if the poller supports the given events +-- +-- @param events the events to check +-- @return true if supported +-- function poller:support(events) return io.poller_support(events) end --- spank poller to break the wait() and return all triggered events +-- spank the poller to break wait() and return immediately function poller:spank() io.poller_spank() end -- insert object events to poller +-- +-- @param obj the object (pipe, socket, process, fwatcher) +-- @param events the events to monitor +-- @param udata the user data (optional) +-- @return true on success, or false and error info +-- function poller:insert(obj, events, udata) -- insert it @@ -81,6 +91,12 @@ function poller:insert(obj, events, udata) end -- modify object events in poller +-- +-- @param obj the object +-- @param events the new events to monitor +-- @param udata the user data (optional) +-- @return true on success, or false and error info +-- function poller:modify(obj, events, udata) -- modify it @@ -95,6 +111,10 @@ function poller:modify(obj, events, udata) end -- remove object from poller +-- +-- @param obj the object to remove +-- @return true on success, or false and error info +-- function poller:remove(obj) -- remove it @@ -108,7 +128,11 @@ function poller:remove(obj) return true end --- wait object events in poller +-- wait for object events in poller +-- +-- @param timeout the timeout in milliseconds, -1 for infinite +-- @return the number of events, or -1 on error +-- function poller:wait(timeout) -- wait it diff --git a/xmake/core/base/process.lua b/xmake/core/base/process.lua index 692a6360f..35b0b15b7 100644 --- a/xmake/core/base/process.lua +++ b/xmake/core/base/process.lua @@ -51,6 +51,9 @@ function _subprocess.new(program, proc) end -- get the process name +-- +-- @return the process name string +-- function _subprocess:name() if not self._NAME then self._NAME = path.filename(self:program()) @@ -58,7 +61,10 @@ function _subprocess:name() return self._NAME end --- get the process program +-- get the process program path +-- +-- @return the program path string +-- function _subprocess:program() return self._PROGRAM end @@ -101,7 +107,10 @@ function _subprocess:wait(timeout) return result, status_or_errors end --- kill subprocess +-- kill the subprocess +-- +-- @return true on success +-- function _subprocess:kill() -- ensure opened @@ -115,7 +124,10 @@ function _subprocess:kill() return true end --- close subprocess +-- close the subprocess and release resources +-- +-- @return true on success +-- function _subprocess:close() -- ensure opened @@ -305,7 +317,12 @@ function process._get_missing_dlls(program) return missing end --- get process exit errors +-- get process exit error message +-- +-- @param program the program path +-- @param exitcode the exit code +-- @return the error message string, or nil +-- function process.get_exit_errors(program, exitcode) local errors if os.is_host("windows") then diff --git a/xmake/core/base/profiler.lua b/xmake/core/base/profiler.lua index c00d80964..c26c96645 100644 --- a/xmake/core/base/profiler.lua +++ b/xmake/core/base/profiler.lua @@ -165,7 +165,7 @@ function profiler:start() end end --- stop profiling +-- stop profiling and print results function profiler:stop() if self:is_trace() then debug.sethook() @@ -231,7 +231,11 @@ function profiler:stop() end end --- enter the given tag for perf:tag +-- enter the given performance tag +-- +-- @param name the tag name +-- @param ... the format arguments for tag name +-- function profiler:enter(name, ...) local is_perf_tag = self._IS_PERF_TAG if is_perf_tag == nil then @@ -246,7 +250,11 @@ function profiler:enter(name, ...) end end --- leave the given tag for perf:tag +-- leave the given performance tag +-- +-- @param name the tag name +-- @param ... the format arguments for tag name +-- function profiler:leave(name, ...) local is_perf_tag = self._IS_PERF_TAG if is_perf_tag == nil then @@ -264,7 +272,10 @@ function profiler:leave(name, ...) end end --- get profiler mode, e.g. perf:call, perf:tag, perf:process, trace +-- get profiler mode +-- +-- @return the mode string, e.g. "perf:call", "perf:tag", "perf:process", "trace" +-- function profiler:mode() local mode = self._MODE if mode == nil then @@ -274,13 +285,20 @@ function profiler:mode() return mode or nil end --- is trace? +-- is trace mode? +-- +-- @return true if trace mode +-- function profiler:is_trace() local mode = self:mode() return mode and mode == "trace" end --- is perf? +-- is perf mode? +-- +-- @param name the specific perf type (optional), e.g. "call", "tag", "process" +-- @return true if perf mode +-- function profiler:is_perf(name) local mode = self:mode() if mode and name then @@ -288,7 +306,10 @@ function profiler:is_perf(name) end end --- profiler is enabled? +-- is the profiler enabled? +-- +-- @return true if enabled via --profile option +-- function profiler:enabled() return self:is_perf("call") or self:is_perf("tag") or self:is_trace() end diff --git a/xmake/core/base/queue.lua b/xmake/core/base/queue.lua index e7f306c11..543518356 100644 --- a/xmake/core/base/queue.lua +++ b/xmake/core/base/queue.lua @@ -24,20 +24,26 @@ local object = require("base/object") -- define module local queue = queue or object {_init = {"_first", "_last"}} {1, 0} --- clear queue +-- clear all elements function queue:clear() self._first = 1 self._last = 0 end --- push item to queue +-- push an item to the back of the queue +-- +-- @param item the item to push +-- function queue:push(item) local last = self._last + 1 self._last = last self[last] = item end --- pop item from queue +-- pop an item from the front of the queue +-- +-- @return the popped item, or nil if empty +-- function queue:pop() local first = self._first if first > self._last then @@ -50,17 +56,26 @@ function queue:pop() return value end --- get queue size +-- get the queue size +-- +-- @return the number of elements +-- function queue:size() return self._last - self._first + 1 end --- is queue empty? +-- is the queue empty? +-- +-- @return true if empty +-- function queue:empty() return self._first > self._last end --- peek the first item of queue +-- peek the first item without removing +-- +-- @return the first element, or nil if empty +-- function queue:first() if self._first > self._last then return nil @@ -68,7 +83,10 @@ function queue:first() return self[self._first] end --- peek the last item of queue +-- peek the last item without removing +-- +-- @return the last element, or nil if empty +-- function queue:last() if self._first > self._last then return nil @@ -107,7 +125,10 @@ function queue:ritems() end end --- clone queue +-- clone the queue +-- +-- @return the cloned queue +-- function queue:clone() local q = queue.new() for i = self._first, self._last do diff --git a/xmake/core/base/scheduler.lua b/xmake/core/base/scheduler.lua index 060ceb616..a59c38207 100644 --- a/xmake/core/base/scheduler.lua +++ b/xmake/core/base/scheduler.lua @@ -483,16 +483,33 @@ function scheduler:_profiler() end -- start a new coroutine task +-- +-- @param cotask the coroutine task function +-- @param ... the task arguments +-- @return the coroutine object +-- function scheduler:co_start(cotask, ...) return self:co_start_named(nil, cotask, ...) end -- start a new named coroutine task +-- +-- @param coname the coroutine name for debugging +-- @param cotask the coroutine task function +-- @param ... the task arguments +-- @return the coroutine object +-- function scheduler:co_start_named(coname, cotask, ...) return self:co_start_withopt({name = coname}, cotask, ...) end -- start a new coroutine task with options +-- +-- @param opt the options, e.g. {name = "xxx", isolate = true} +-- @param cotask the coroutine task function +-- @param ... the task arguments +-- @return the coroutine object +-- function scheduler:co_start_withopt(opt, cotask, ...) -- check coroutine task @@ -543,6 +560,11 @@ function scheduler:co_start_withopt(opt, cotask, ...) end -- resume the given coroutine +-- +-- @param co the coroutine object +-- @param ... the resume arguments +-- @return true on success, and the yield results +-- function scheduler:co_resume(co, ...) -- do resume @@ -570,6 +592,10 @@ function scheduler:co_resume(co, ...) end -- suspend the current coroutine +-- +-- @param ... the suspend results to return to resume caller +-- @return the resume arguments +-- function scheduler:co_suspend(...) -- suspend it @@ -594,12 +620,15 @@ function scheduler:co_suspend(...) return table.unpack(results) end --- yield the current coroutine +-- yield the current coroutine (give up execution temporarily) function scheduler:co_yield() return scheduler.co_sleep(self, 1) end --- sleep some times (ms) +-- sleep the current coroutine for given milliseconds +-- +-- @param ms the sleep time in milliseconds +-- function scheduler:co_sleep(ms) -- we don't need to sleep @@ -631,7 +660,10 @@ function scheduler:co_sleep(ms) return true end --- lock the current coroutine +-- lock the current coroutine (cooperative lock by name) +-- +-- @param lockname the lock name +-- function scheduler:co_lock(lockname) -- get the running coroutine @@ -682,6 +714,9 @@ function scheduler:co_lock(lockname) end -- unlock the current coroutine +-- +-- @param lockname the lock name +-- function scheduler:co_unlock(lockname) -- get the running coroutine @@ -713,6 +748,10 @@ function scheduler:co_unlock(lockname) end -- get the given coroutine group +-- +-- @param name the group name +-- @return the coroutines table in this group +-- function scheduler:co_group(name) return self._CO_GROUPS and self._CO_GROUPS[name] end @@ -742,7 +781,12 @@ function scheduler:co_group_begin(name, scopefunc) return true end --- wait for finishing the given coroutine group +-- wait for finishing all coroutines in the given group +-- +-- @param name the group name +-- @param opt the options, e.g. {limit = 8} +-- @return true on success, or errors +-- function scheduler:co_group_wait(name, opt) -- get coroutine group @@ -815,6 +859,9 @@ function scheduler:co_group_waitobjs(name) end -- get the current running coroutine +-- +-- @return the current coroutine object +-- function scheduler:co_running() if self._ENABLED then local running = coroutine.running() @@ -823,6 +870,9 @@ function scheduler:co_running() end -- get all coroutine tasks +-- +-- @return the tasks table +-- function scheduler:co_tasks() local cotasks = self._CO_TASKS if not cotasks then diff --git a/xmake/core/base/socket.lua b/xmake/core/base/socket.lua index fb4536e24..393edd199 100644 --- a/xmake/core/base/socket.lua +++ b/xmake/core/base/socket.lua @@ -131,7 +131,12 @@ function _instance:ctrl(code, value) return ok, errors end --- bind socket +-- bind socket to address and port +-- +-- @param addr the bind address +-- @param port the bind port +-- @return true on success, or false and error info +-- function _instance:bind(addr, port) -- ensure opened @@ -171,7 +176,11 @@ function _instance:bind_unix(addr, opt) return ok, errors end --- listen socket +-- listen for incoming connections +-- +-- @param backlog the maximum pending connections +-- @return true on success, or false and error info +-- function _instance:listen(backlog) -- ensure opened @@ -188,7 +197,11 @@ function _instance:listen(backlog) return ok, errors end --- accept socket +-- accept an incoming connection +-- +-- @param opt the options (optional) +-- @return the client socket, or nil on timeout +-- function _instance:accept(opt) -- ensure opened @@ -217,7 +230,13 @@ function _instance:accept(opt) return sock, errors end --- connect socket +-- connect to remote address and port +-- +-- @param addr the remote address +-- @param port the remote port +-- @param opt the options (optional) +-- @return 1 on success, 0 on timeout, -1 on error +-- function _instance:connect(addr, port, opt) -- ensure opened @@ -281,6 +300,11 @@ function _instance:connect_unix(addr, opt) end -- send data to socket +-- +-- @param data the data to send (string or bytes) +-- @param opt the options, e.g. {block = true} +-- @return the real sent size, or -1 on error +-- function _instance:send(data, opt) -- ensure opened @@ -346,7 +370,12 @@ function _instance:send(data, opt) return send, errors end --- send file to socket +-- send file data to socket (zero-copy) +-- +-- @param file the file object +-- @param opt the options (optional) +-- @return the real sent size, or -1 on error +-- function _instance:sendfile(file, opt) -- ensure the socket opened @@ -415,7 +444,13 @@ function _instance:sendfile(file, opt) return send, errors end --- recv data from socket +-- receive data from socket +-- +-- @param buff the buffer to receive data +-- @param size the max receive size +-- @param opt the options, e.g. {block = true} +-- @return the real received size, or -1 on error +-- function _instance:recv(buff, size, opt) assert(buff) @@ -488,7 +523,14 @@ function _instance:recv(buff, size, opt) return recv, data_or_errors end --- send udp data to peer +-- send UDP data to peer +-- +-- @param data the data to send +-- @param addr the peer address +-- @param port the peer port +-- @param opt the options (optional) +-- @return the real sent size, or -1 on error +-- function _instance:sendto(data, addr, port, opt) -- ensure opened @@ -553,7 +595,13 @@ function _instance:sendto(data, addr, port, opt) return send, errors end --- recv udp data from peer +-- receive UDP data from peer +-- +-- @param buff the buffer to receive data +-- @param size the max receive size +-- @param opt the options (optional) +-- @return the real received size, the peer address, the peer port +-- function _instance:recvfrom(buff, size, opt) assert(buff) @@ -624,7 +672,12 @@ function _instance:recvfrom(buff, size, opt) return recv, data_or_errors, addr, port end --- wait socket events +-- wait for socket events +-- +-- @param events the events to wait, e.g. socket.EV_RECV, socket.EV_SEND +-- @param timeout the timeout in milliseconds, -1 for infinite +-- @return the received events, or 0 on timeout +-- function _instance:wait(events, timeout) -- ensure opened @@ -661,7 +714,10 @@ function _instance:kill() return true end --- close socket +-- close the socket +-- +-- @return true on success +-- function _instance:close() -- ensure opened diff --git a/xmake/core/base/task.lua b/xmake/core/base/task.lua index 29cca38f2..27ad5023a 100644 --- a/xmake/core/base/task.lua +++ b/xmake/core/base/task.lua @@ -365,7 +365,12 @@ function task.apis() } end --- new a task instance +-- create a new task instance +-- +-- @param name the task name +-- @param info the task info table +-- @return the task instance +-- function task.new(name, info) local instance = table.inherit(task) if name then @@ -380,7 +385,10 @@ function task.new(name, info) return instance end --- get global tasks +-- get all registered tasks +-- +-- @return the tasks table {name = task, ...} +-- function task.tasks() if task._TASKS then return task._TASKS @@ -410,12 +418,20 @@ function task.tasks() return instances end --- get the given global task +-- get the given task by name +-- +-- @param name the task name +-- @return the task instance, or nil if not found +-- function task.task(name) return task.tasks()[name] end --- get the task menu +-- get the task menu for command line parsing +-- +-- @param tasks the tasks table (optional, default all tasks) +-- @return the menu table +-- function task.menu(tasks) local menu = {} for taskname, taskinst in pairs(tasks) do diff --git a/xmake/core/base/timer.lua b/xmake/core/base/timer.lua index 98eef80a3..30f4bafb3 100644 --- a/xmake/core/base/timer.lua +++ b/xmake/core/base/timer.lua @@ -35,7 +35,13 @@ function timer:_tasks() return self._TASKS end --- post timer task after delay and will be auto-remove it after be expired +-- post a timer task after delay (auto-removed after expiration) +-- +-- @param func the callback function +-- @param delay the delay in milliseconds +-- @param opt the options, e.g. {continuous = true} +-- @return the task handle (set task.cancel = true to cancel) +-- function timer:post(func, delay, opt) return self:post_at(func, os.mclock() + delay, delay, opt) end @@ -51,12 +57,22 @@ function timer:post_at(func, when, period, opt) return task end --- post timer task after the relative time and will be auto-remove it after be expired +-- post a timer task after the relative time with optional repeat period +-- +-- @param func the callback function +-- @param after the initial delay in milliseconds +-- @param period the repeat period in milliseconds (0 for one-shot) +-- @param opt the options, e.g. {continuous = true} +-- @return the task handle +-- function timer:post_after(func, after, period, opt) return self:post_at(func, os.mclock() + after, period, opt) end --- get the delay of next task +-- get the delay until the next task fires +-- +-- @return the delay in milliseconds, or -1 if no tasks +-- function timer:delay() local delay = nil local tasks = self:_tasks() @@ -70,7 +86,7 @@ function timer:delay() return delay end --- run the timer next loop +-- run the next timer loop, executing expired tasks function timer:next() local tasks = self:_tasks() while tasks:length() > 0 do @@ -101,7 +117,7 @@ function timer:next() return true end --- kill all timer tasks +-- kill all pending timer tasks function timer:kill() local tasks = self:_tasks() while tasks:length() > 0 do @@ -129,7 +145,11 @@ function timer:init(name) end} end --- new timer +-- create a new timer +-- +-- @param name the timer name for debugging +-- @return the timer instance +-- function timer:new(name) self = self() self:init(name) diff --git a/xmake/core/base/tty.lua b/xmake/core/base/tty.lua index bd7b60277..2b9aa91bc 100644 --- a/xmake/core/base/tty.lua +++ b/xmake/core/base/tty.lua @@ -496,7 +496,10 @@ function tty.has_emoji() return has_emoji end --- has vtansi? +-- does the terminal support VT/ANSI escape codes? +-- +-- @return true if supported +-- function tty.has_vtansi() return tty.has_color8() end @@ -658,7 +661,10 @@ function tty.term_mode(stdtype, newmode) return oldmode end --- get session id +-- get the terminal session id +-- +-- @return the session id string +-- function tty.session_id() local session_id = tty._SESSION_ID if session_id == nil then diff --git a/xmake/core/base/utils.lua b/xmake/core/base/utils.lua index ddf8c127f..771dc09f7 100644 --- a/xmake/core/base/utils.lua +++ b/xmake/core/base/utils.lua @@ -31,7 +31,10 @@ local dump = require("base/dump") local text = require("base/text") --- dump values +-- dump values with colored pretty-printing +-- +-- @param ... the values to dump +-- function utils.dump(...) if option.get("quiet") then return ... @@ -142,6 +145,10 @@ function utils._decode_errors(errors) end -- print format string with newline +-- +-- @param format the format string +-- @param ... the format arguments +-- function utils.print(format, ...) assert(format) local message = string.tryformat(format, ...) @@ -150,6 +157,10 @@ function utils.print(format, ...) end -- print format string without newline +-- +-- @param format the format string +-- @param ... the format arguments +-- function utils.printf(format, ...) assert(format) local message = string.tryformat(format, ...) @@ -157,7 +168,11 @@ function utils.printf(format, ...) log:write(message) end --- print format string and colors with newline +-- print format string with color markup and newline +-- +-- @param format the format string with ${color} markup +-- @param ... the format arguments +-- function utils.cprint(format, ...) assert(format) local message = string.tryformat(format, ...) @@ -167,7 +182,11 @@ function utils.cprint(format, ...) end end --- print format string and colors without newline +-- print format string with color markup without newline +-- +-- @param format the format string with ${color} markup +-- @param ... the format arguments +-- function utils.cprintf(format, ...) assert(format) local message = string.tryformat(format, ...) @@ -177,7 +196,11 @@ function utils.cprintf(format, ...) end end --- print the verbose information +-- print the verbose information (only when -v is enabled) +-- +-- @param format the format string +-- @param ... the format arguments +-- function utils.vprint(format, ...) if (option.get("verbose") or option.get("diagnosis")) and format ~= nil then utils.print(format, ...) @@ -191,7 +214,11 @@ function utils.vprintf(format, ...) end end --- print the diagnosis information +-- print the diagnosis information (only when -D is enabled) +-- +-- @param format the format string +-- @param ... the format arguments +-- function utils.dprint(format, ...) if option.get("diagnosis") and format ~= nil then utils.print(format, ...) @@ -205,7 +232,11 @@ function utils.dprintf(format, ...) end end --- print the error information +-- print the error information to stderr +-- +-- @param format the format string +-- @param ... the format arguments +-- function utils.error(format, ...) if format ~= nil then local errors = string.tryformat(format, ...) @@ -218,7 +249,11 @@ function utils.error(format, ...) end end --- add warning message +-- add a warning message (displayed at the end of execution) +-- +-- @param format the format string +-- @param ... the format arguments +-- function utils.warning(format, ...) if option.get("quiet") then return @@ -253,7 +288,13 @@ function utils.show_warnings() end end --- try to call script +-- try to call script safely +-- +-- @param script the script function +-- @param traceback the traceback function (optional) +-- @param ... the script arguments +-- @return true and results on success, or false and errors +-- function utils.trycall(script, traceback, ...) return xpcall(script, function (errors) diff --git a/xmake/core/base/xmake.lua b/xmake/core/base/xmake.lua index d25e60147..53971de8c 100644 --- a/xmake/core/base/xmake.lua +++ b/xmake/core/base/xmake.lua @@ -24,12 +24,18 @@ local xmake = xmake or {} -- load modules local semver = require("base/semver") --- get name +-- get xmake program name +-- +-- @return the name string, e.g. "xmake" +-- function xmake.name() return xmake._NAME or "xmake" end --- get xmake version, e.g. v2.5.8+dev.d4cff6e11 +-- get xmake version +-- +-- @return the semver version object, e.g. xmake.version():ge("3.0.0") +-- function xmake.version() if xmake._VERSION_CACHE == nil then xmake._VERSION_CACHE = semver.new(xmake._VERSION) or false @@ -38,41 +44,65 @@ function xmake.version() end -- get the xmake binary architecture +-- +-- @return the architecture string, e.g. "x86_64", "arm64" +-- function xmake.arch() return xmake._XMAKE_ARCH end --- get the git branch of xmake version, e.g. build: {"dev", "d4cff6e11"} +-- get the git branch and commit of xmake version +-- +-- @return the branch string and commit hash +-- function xmake.branch() return xmake.version():build()[1] end --- get the program directory +-- get the xmake program scripts directory +-- +-- @return the program directory path +-- function xmake.programdir() return xmake._PROGRAM_DIR end --- get the program file +-- get the xmake program binary file path +-- +-- @return the program file path +-- function xmake.programfile() return xmake._PROGRAM_FILE end --- use luajit? +-- is using LuaJIT runtime? +-- +-- @return true if LuaJIT +-- function xmake.luajit() return xmake._LUAJIT end --- is embed? +-- is embedded via libxmake (xmake.cli)? +-- +-- @return true if embedded +-- function xmake.is_embed() return xmake._EMBED or false end --- in main thread? +-- is running in the main thread? +-- +-- @return true if in main thread +-- function xmake.in_main_thread() return xmake._THREAD_CALLBACK == nil end --- get command arguments +-- get the command line arguments +-- +-- @return the arguments array +-- function xmake.argv() return xmake._ARGV end diff --git a/xmake/core/package/component.lua b/xmake/core/package/component.lua index d93a4f7fb..c55dc4a73 100644 --- a/xmake/core/package/component.lua +++ b/xmake/core/package/component.lua @@ -46,36 +46,63 @@ function _instance.new(name, opt) end -- get the component name +-- +-- @return the component name string +-- function _instance:name() return self._NAME end --- get the type: component +-- get the instance type +-- +-- @return "component" +-- function _instance:type() return "component" end --- get the it's package +-- get the parent package +-- +-- @return the package instance +-- function _instance:package() return self._PACKAGE end --- get the component configuration +-- get the component configuration value +-- +-- @param name the config name +-- @return the config value +-- function _instance:get(name) return self._INFO:get(name) end -- set the value to the component info +-- +-- @param name the info name +-- @param ... the values +-- function _instance:set(name, ...) self._INFO:apival_set(name, ...) end -- add the value to the component info +-- +-- @param name the info name +-- @param ... the values to add +-- function _instance:add(name, ...) self._INFO:apival_add(name, ...) end -- get the extra configuration +-- +-- @param name the config name +-- @param item the config item +-- @param key the config key (optional) +-- @return the extra config value +-- function _instance:extraconf(name, item, key) local conf = self._INFO:extraconf(name, item, key) if conf == nil then diff --git a/xmake/core/package/package.lua b/xmake/core/package/package.lua index 6b725c404..1107e03b0 100644 --- a/xmake/core/package/package.lua +++ b/xmake/core/package/package.lua @@ -94,6 +94,9 @@ function _instance:memcache() end -- get the package name without namespace +-- +-- @return the package name string +-- function _instance:name() return self._NAME end @@ -129,7 +132,11 @@ function _instance:base() return self._BASE end --- get the package configuration +-- get the package configuration value +-- +-- @param name the config name +-- @return the config value +-- function _instance:get(name) local value = self._INFO:get(name) if name == "configs" then @@ -149,6 +156,10 @@ function _instance:get(name) end -- set the value to the package info +-- +-- @param name the info name +-- @param ... the values +-- function _instance:set(name, ...) if self._SOURCE_INITED then -- we can use set/add to modify urls, .. in on_load() if urls have been inited. @@ -202,7 +213,10 @@ function _instance:description() return self:get("description") end --- get the platform of package +-- get the platform of package, e.g. "windows", "linux", "macosx" +-- +-- @return the platform name +-- function _instance:plat() if self._PLAT then return self._PLAT @@ -217,7 +231,10 @@ function _instance:plat() return package.targetplat() end --- get the architecture of package +-- get the architecture of package, e.g. "x86_64", "arm64" +-- +-- @return the architecture name +-- function _instance:arch() if self._ARCH then return self._ARCH @@ -266,7 +283,11 @@ function _instance:repo() return self._REPO end --- the current platform is belong to the given platforms? +-- is the package platform belong to the given platforms? +-- +-- @param ... the platform names +-- @return true if matched +-- function _instance:is_plat(...) local plat = self:plat() for _, v in ipairs(table.pack(...)) do @@ -276,7 +297,11 @@ function _instance:is_plat(...) end end --- the current architecture is belong to the given architectures? +-- is the package architecture belong to the given architectures? +-- +-- @param ... the architecture names +-- @return true if matched +-- function _instance:is_arch(...) local arch = self:arch() for _, v in ipairs(table.pack(...)) do @@ -325,7 +350,10 @@ function _instance:extsources() return self:get("extsources") end --- get urls +-- get the source urls +-- +-- @return the urls array +-- function _instance:urls() return self:current_scheme():urls() end @@ -570,6 +598,9 @@ function _instance:kind() end -- is binary package? +-- +-- @return true if the package kind is "binary" +-- function _instance:is_binary() return self:kind() == "binary" or self:kind() == "toolchain" end @@ -580,6 +611,9 @@ function _instance:is_toolchain() end -- is library package? +-- +-- @return true if the package kind is "library" or default +-- function _instance:is_library() return self:kind() == nil or self:kind() == "library" end @@ -589,7 +623,10 @@ function _instance:is_template() return self:kind() == "template" end --- is header only? +-- is header-only library? +-- +-- @return true if the package kind is "headeronly" +-- function _instance:is_headeronly() return self:is_library() and self:extraconf("kind", "library", "headeronly") end @@ -790,11 +827,17 @@ function _instance:unlock() end -- get the source directory +-- +-- @return the source directory path +-- function _instance:sourcedir() return self:get("sourcedir") end -- get the build directory +-- +-- @return the build directory path +-- function _instance:builddir() local builddir = self._BUILDDIR if not builddir then @@ -817,6 +860,9 @@ function _instance:buildir() end -- get the cached directory of this package +-- +-- @return the cache directory path +-- function _instance:cachedir() local cachedir = self._CACHEDIR if not cachedir then @@ -851,6 +897,10 @@ function _instance:cachedir() end -- get the installed directory of this package +-- +-- @param ... the subdirectory components (optional) +-- @return the install directory path +-- function _instance:installdir(...) local installdir = self._INSTALLDIR if not installdir then diff --git a/xmake/core/package/repository.lua b/xmake/core/package/repository.lua index 7f140c098..8141d53d2 100644 --- a/xmake/core/package/repository.lua +++ b/xmake/core/package/repository.lua @@ -48,21 +48,33 @@ end -- get the repository name +-- +-- @return the name string +-- function _instance:name() return self._NAME end -- get the repository url +-- +-- @return the url string +-- function _instance:url() return self._URL end -- get the repository branch +-- +-- @return the branch string +-- function _instance:branch() return self._BRANCH end --- get the current commit +-- get the current commit hash +-- +-- @return the commit string +-- function _instance:commit() return self._COMMIT end @@ -73,11 +85,17 @@ function _instance:commit_set(commit) end -- is global repository? +-- +-- @return true if global +-- function _instance:is_global() return self._IS_GLOBAL end --- get the repository directory +-- get the repository directory on disk +-- +-- @return the directory path +-- function _instance:directory() return self._DIRECTORY end @@ -125,7 +143,11 @@ function repository.apis() } end --- get the local or global repository directory +-- get the repositories root directory +-- +-- @param is_global get global directory if true +-- @return the directory path +-- function repository.directory(is_global) -- get directory @@ -136,7 +158,14 @@ function repository.directory(is_global) end end --- load the repository +-- load a repository +-- +-- @param name the repository name +-- @param url the repository url +-- @param branch the repository branch +-- @param is_global is global repository? +-- @return the repository instance +-- function repository.load(name, url, branch, is_global) -- check url @@ -165,6 +194,11 @@ function repository.load(name, url, branch, is_global) end -- get repository url from the given name +-- +-- @param name the repository name +-- @param is_global search global repositories? +-- @return the repository url +-- function repository.get(name, is_global) -- get it @@ -179,7 +213,13 @@ function repository.get(name, is_global) end end --- add repository url to the given name +-- add a repository +-- +-- @param name the repository name +-- @param url the repository url +-- @param branch the repository branch +-- @param is_global add as global repository? +-- function repository.add(name, url, branch, is_global) -- no name? @@ -199,7 +239,11 @@ function repository.add(name, url, branch, is_global) return true end --- remove repository from gobal or local directory +-- remove a repository +-- +-- @param name the repository name +-- @param is_global remove from global? +-- function repository.remove(name, is_global) -- get repositories @@ -225,7 +269,11 @@ function repository.clear(is_global) end --- get all repositories from global or local directory +-- get all repositories +-- +-- @param is_global get global repositories? +-- @return the repositories table {name = repo, ...} +-- function repository.repositories(is_global) return repository._cache(is_global):get("repositories") end diff --git a/xmake/core/package/scheme.lua b/xmake/core/package/scheme.lua index d03cce0a9..a1baa7301 100644 --- a/xmake/core/package/scheme.lua +++ b/xmake/core/package/scheme.lua @@ -51,31 +51,50 @@ function _instance.new(name, opt) end -- get the scheme name +-- +-- @return the scheme name string +-- function _instance:name() return self._NAME end --- get the type: scheme +-- get the instance type +-- +-- @return "scheme" +-- function _instance:type() return "scheme" end --- is default scheme? +-- is the default scheme? +-- +-- @return true if default +-- function _instance:is_default() return self:name() == "__default__" end --- is precompiled scheme? +-- is precompiled binary scheme? +-- +-- @return true if precompiled +-- function _instance:is_precompiled() return self:name() == "__precompiled__" end --- get the it's package +-- get the associated package +-- +-- @return the package instance +-- function _instance:package() return self._PACKAGE end --- get the scheme configuration +-- get the scheme configuration value +-- +-- @param name the config name +-- @return the config value +-- function _instance:get(name) local value = self._INFO:get(name) if value == nil and self:is_default() and self:package() then @@ -85,6 +104,10 @@ function _instance:get(name) end -- set the value to scheme info +-- +-- @param name the info name +-- @param ... the values +-- function _instance:set(name, ...) self._INFO:apival_set(name, ...) end @@ -108,7 +131,10 @@ function _instance:extraconf_set(name, item, key, value) return self._INFO:extraconf_set(name, item, key, value) end --- get urls +-- get the source urls +-- +-- @return the urls array +-- function _instance:urls() local urls = self._URLS if urls == nil then diff --git a/xmake/core/project/cache.lua b/xmake/core/project/cache.lua index 280df52e8..669ec1a03 100644 --- a/xmake/core/project/cache.lua +++ b/xmake/core/project/cache.lua @@ -86,22 +86,30 @@ function cache._instance(scopename) return instance end --- get the value +-- get the cached value +-- +-- @param name the cache key +-- @return the cached value +-- function cache:get(name) return self._CACHEDATA[name] end --- set the value +-- set the cached value +-- +-- @param name the cache key +-- @param value the value to cache +-- function cache:set(name, value) self._CACHEDATA[name] = value end --- clear all +-- clear all cached values function cache:clear() self._CACHEDATA = {__version = xmake._VERSION_SHORT} end --- flush to cache file +-- flush cached values to file function cache:flush() -- flush the version diff --git a/xmake/core/project/option.lua b/xmake/core/project/option.lua index f754b4efc..62687a106 100644 --- a/xmake/core/project/option.lua +++ b/xmake/core/project/option.lua @@ -388,11 +388,17 @@ function _instance:check() end -- get the option value +-- +-- @return the option value +-- function _instance:value() return config.get(self:fullname()) end -- set the option value +-- +-- @param value the value to set +-- function _instance:set_value(value) config.set(self:fullname(), value) self:_save() @@ -404,7 +410,10 @@ function _instance:clear() self:_clear() end --- this option is enabled? +-- is this option enabled? +-- +-- @return true if enabled +-- function _instance:enabled() return config.get(self:fullname()) end @@ -437,12 +446,19 @@ function _instance:info() return self._INFO:info() end --- get the type: option +-- get the instance type +-- +-- @return "option" +-- function _instance:type() return "option" end --- get the option info +-- get the option info value +-- +-- @param name the info name +-- @return the info value +-- function _instance:get(name) return self._INFO:get(name) end diff --git a/xmake/core/project/policy.lua b/xmake/core/project/policy.lua index 0cf184d91..617a792d6 100644 --- a/xmake/core/project/policy.lua +++ b/xmake/core/project/policy.lua @@ -30,6 +30,9 @@ local utils = require("base/utils") local string = require("base/string") -- get all defined policies +-- +-- @return the policies table {name = {description, ...}, ...} +-- function policy.policies() local policies = policy._POLICIES if not policies then @@ -212,6 +215,10 @@ function policy.policies() end -- set policy default value +-- +-- @param name the policy name, e.g. "build.ccache" +-- @param value the default value +-- function policy.set_default(name, value) local defined_policy = policy.policies()[name] if defined_policy then @@ -221,7 +228,12 @@ function policy.set_default(name, value) end end --- check policy value +-- check and validate policy value +-- +-- @param name the policy name +-- @param value the value to check +-- @return the validated value +-- function policy.check(name, value) local defined_policy = policy.policies()[name] if defined_policy then diff --git a/xmake/core/project/rule.lua b/xmake/core/project/rule.lua index c11c6e246..790f715fa 100644 --- a/xmake/core/project/rule.lua +++ b/xmake/core/project/rule.lua @@ -84,24 +84,42 @@ function _instance:clone() return instance end --- get the rule info +-- get the rule info value +-- +-- @param name the info name +-- @return the info value +-- function _instance:get(name) return self._INFO:get(name) end -- set the value to the rule info +-- +-- @param name the info name +-- @param ... the values +-- function _instance:set(name, ...) self._INFO:apival_set(name, ...) self:_invalidate(name) end -- add the value to the rule info +-- +-- @param name the info name +-- @param ... the values to add +-- function _instance:add(name, ...) self._INFO:apival_add(name, ...) self:_invalidate(name) end -- get the extra configuration +-- +-- @param name the config name +-- @param item the config item +-- @param key the config key (optional) +-- @return the extra config value +-- function _instance:extraconf(name, item, key) return self._INFO:extraconf(name, item, key) end @@ -112,6 +130,9 @@ function _instance:extraconf_set(name, item, key, value) end -- get the rule name +-- +-- @return the rule name string +-- function _instance:name() return self._NAME end @@ -171,7 +192,12 @@ function _instance:orderdeps() return self._ORDERDEPS end --- get xxx_script +-- get the rule script function (on_build, on_install, etc.) +-- +-- @param name the script name, e.g. "build", "install", "clean" +-- @param generic use generic script if platform-specific not found? +-- @return the script function +-- function _instance:script(name, generic) -- get script diff --git a/xmake/core/project/target.lua b/xmake/core/project/target.lua index aa204a054..1c568de65 100644 --- a/xmake/core/project/target.lua +++ b/xmake/core/project/target.lua @@ -718,12 +718,20 @@ function _instance:get_from(name, sources, opt) end -- set the value to the target info +-- +-- @param name the info name +-- @param ... the values +-- function _instance:set(name, ...) self._INFO:apival_set(name, ...) self:_invalidate(name) end -- add the value to the target info +-- +-- @param name the info name +-- @param ... the values to add +-- function _instance:add(name, ...) self._INFO:apival_add(name, ...) self:_invalidate(name) @@ -825,11 +833,19 @@ function _instance:sourceinfo(name, item) end -- get user private data +-- +-- @param name the data key +-- @return the data value +-- function _instance:data(name) return self._DATA and self._DATA[name] end -- set user private data +-- +-- @param name the data key +-- @param data the data value +-- function _instance:data_set(name, data) self._DATA = self._DATA or {} self._DATA[name] = data @@ -841,7 +857,12 @@ function _instance:data_add(name, data) self._DATA[name] = table.unwrap(table.join(self._DATA[name] or {}, data)) end --- get values +-- get values set by set_values/add_values +-- +-- @param name the values name, e.g. "csharp.target_framework" +-- @param sourcefile the source file (optional, for file-level values) +-- @return the values +-- function _instance:values(name, sourcefile) -- get values from the source file first @@ -892,6 +913,9 @@ function _instance:type() end -- get the target name +-- +-- @return the target name string +-- function _instance:name() return self._NAME end @@ -917,7 +941,10 @@ function _instance:fullname() return namespace and namespace .. "::" .. self:name() or self:name() end --- get the target kind +-- get the target kind, e.g. "binary", "shared", "static", "object", "headeronly" +-- +-- @return the kind string +-- function _instance:kind() return self:get("kind") or "binary" end @@ -927,17 +954,27 @@ function _instance:targetkind() return self:kind() end --- get the platform of this target +-- get the platform of this target, e.g. "windows", "linux", "macosx" +-- +-- @return the platform name +-- function _instance:plat() return self:get("plat") or config.get("plat") or os.host() end --- get the architecture of this target +-- get the architecture of this target, e.g. "x86_64", "arm64" +-- +-- @return the architecture name +-- function _instance:arch() return self:get("arch") or config.get("arch") or os.arch() end --- the current target is belong to the given platforms? +-- is the current target belong to the given platforms? +-- +-- @param ... the platform names, e.g. "windows", "linux" +-- @return true if matched +-- function _instance:is_plat(...) local plat = self:plat() for _, v in ipairs(table.pack(...)) do @@ -947,7 +984,11 @@ function _instance:is_plat(...) end end --- the current target is belong to the given architectures? +-- is the current target belong to the given architectures? +-- +-- @param ... the architecture names, e.g. "x86_64", "arm64" +-- @return true if matched +-- function _instance:is_arch(...) local arch = self:arch() for _, v in ipairs(table.pack(...)) do @@ -1061,6 +1102,9 @@ function _instance:policy(name) end -- get the base name of target file +-- +-- @return the base name without extension +-- function _instance:basename() local filename = self:get("filename") if filename then @@ -1116,6 +1160,10 @@ function _instance:linkflags() end -- get the given dependent target +-- +-- @param name the dependent target name +-- @return the target instance, or nil if not found +-- function _instance:dep(name) local deps = self:deps() if deps then @@ -1130,7 +1178,10 @@ function _instance:dep(name) end end --- get target deps +-- get all dependent targets +-- +-- @return the deps table {name = target, ...} +-- function _instance:deps() if not self:_is_loaded() then os.raise("please call target:deps() or target:dep() in after_load()!") @@ -1141,7 +1192,11 @@ function _instance:deps() return self._DEPS end --- get target ordered deps +-- get dependent targets in dependency order +-- +-- @param opt the options, e.g. {inherit = true} +-- @return the ordered deps array +-- function _instance:orderdeps(opt) opt = opt or {} if not self:_is_loaded() then @@ -1170,6 +1225,10 @@ function _instance:orderules() end -- get target rule from the given rule name +-- +-- @param name the rule name +-- @return the rule instance, or nil if not found +-- function _instance:rule(name) if self._RULES then local r = self._RULES[name] @@ -1213,26 +1272,41 @@ function _instance:is_phony() end -- is binary target? +-- +-- @return true if the target kind is "binary" +-- function _instance:is_binary() return self:kind() == "binary" end -- is shared library target? +-- +-- @return true if the target kind is "shared" +-- function _instance:is_shared() return self:kind() == "shared" end -- is static library target? +-- +-- @return true if the target kind is "static" +-- function _instance:is_static() return self:kind() == "static" end -- is object files target? +-- +-- @return true if the target kind is "object" +-- function _instance:is_object() return self:kind() == "object" end -- is headeronly target? +-- +-- @return true if the target kind is "headeronly" +-- function _instance:is_headeronly() return self:kind() == "headeronly" end @@ -1323,12 +1397,21 @@ function _instance:orderopts(opt) return orderopts end --- get the enabled package +-- get the enabled package by name +-- +-- @param name the package name +-- @param opt the options (optional) +-- @return the package instance, or nil if not found +-- function _instance:pkg(name, opt) return self:pkgs(opt)[name] end --- get the enabled packages +-- get all enabled packages +-- +-- @param opt the options (optional) +-- @return the packages table {name = package, ...} +-- function _instance:pkgs(opt) opt = opt or {} local cachekey = "pkgs" @@ -1348,7 +1431,11 @@ function _instance:pkgs(opt) return packages end --- get the required packages with {interface|public = ..} +-- get the required packages in order +-- +-- @param opt the options (optional) +-- @return the ordered packages array +-- function _instance:orderpkgs(opt) opt = opt or {} local cachekey = "orderpkgs" @@ -1436,6 +1523,10 @@ function _instance:pkgconfig(pkgname) end -- get the object files directory +-- +-- @param opt the options (optional) +-- @return the object directory path +-- function _instance:objectdir(opt) -- the object directory @@ -1509,7 +1600,11 @@ function _instance:dependir(opt) return dependir end --- get the autogen files directory +-- get the auto-generated files directory +-- +-- @param opt the options (optional) +-- @return the autogen directory path +-- function _instance:autogendir(opt) -- init the autogen directory @@ -1623,7 +1718,10 @@ function _instance:_default_targetdir() return targetdir end --- get the target directory +-- get the target output directory +-- +-- @return the target directory path +-- function _instance:targetdir() local targetdir = self:get("targetdir") if not targetdir then @@ -1674,7 +1772,10 @@ function _instance:artifactfile(kind) end end --- get the target file name +-- get the target file name (with prefix, extension) +-- +-- @return the file name string, e.g. "libfoo.a", "foo.exe" +-- function _instance:filename() -- no target file? @@ -1699,7 +1800,10 @@ function _instance:filename() return filename end --- get the link name only for static/shared library +-- get the link name for static/shared library +-- +-- @return the link name string, e.g. "foo" for libfoo.a +-- function _instance:linkname() if self:is_static() or self:is_shared() then local filename = self:get("filename") @@ -1716,7 +1820,10 @@ function _instance:linkname() end end --- get the target file +-- get the target file full path +-- +-- @return the target file path +-- function _instance:targetfile() local filename = self:filename() if filename then @@ -1766,6 +1873,9 @@ function _instance:prefixdir() end -- get the installed binary directory +-- +-- @return the binary install directory path +-- function _instance:bindir() local bindir = baseoption.get("bindir") if bindir then @@ -1779,6 +1889,9 @@ function _instance:bindir() end -- get the installed library directory +-- +-- @return the library install directory path +-- function _instance:libdir() local libdir = baseoption.get("libdir") if libdir then @@ -1804,7 +1917,11 @@ function _instance:includedir() return self:installdir(includedir) end --- get install directory +-- get the install directory +-- +-- @param ... the subdirectory components (optional) +-- @return the install directory path +-- function _instance:installdir(...) opt = opt or {} local installdir = baseoption.get("installdir") @@ -2005,6 +2122,9 @@ function _instance:fileconfig_add(sourcefile, info, opt) end -- get the source files +-- +-- @return the source files array +-- function _instance:sourcefiles() -- cached? return it directly @@ -2113,7 +2233,11 @@ function _instance:sourcefiles() return sourcefiles, true end --- get object file from source file +-- get the object file path from source file +-- +-- @param sourcefile the source file path +-- @return the object file path +-- function _instance:objectfile(sourcefile) return self:autogenfile(sourcefile, {rootdir = self:objectdir(), filename = target.filename(path.filename(sourcefile), "object", { @@ -2122,7 +2246,10 @@ function _instance:objectfile(sourcefile) format = self:_format("object")})}) end --- get the object files +-- get all object files +-- +-- @return the object files array +-- function _instance:objectfiles() -- get source batches @@ -2366,7 +2493,10 @@ function _instance:sourcecount() return #self:sourcefiles() end --- get source batches +-- get source batches grouped by source kind +-- +-- @return the source batches table {sourcekind = {sourcefiles = {...}, ...}, ...} +-- function _instance:sourcebatches() -- get source files @@ -2568,7 +2698,11 @@ function _instance:has_runtime(...) end end --- get the given toolchain +-- get the given toolchain by name +-- +-- @param name the toolchain name, e.g. "gcc", "clang", "msvc" +-- @return the toolchain instance, or nil if not found +-- function _instance:toolchain(name) local toolchains_map = self:memcache():get("toolchains_map") if toolchains_map == nil then @@ -2581,7 +2715,10 @@ function _instance:toolchain(name) return toolchains_map[name] end --- get the toolchains +-- get all toolchains of this target +-- +-- @return the toolchains array +-- function _instance:toolchains() local toolchains = self:memcache():get("toolchains") if toolchains == nil then @@ -2633,6 +2770,10 @@ function _instance:toolchains() end -- get the program and name of the given tool kind +-- +-- @param toolkind the tool kind, e.g. "cc", "cxx", "ld", "sh", "ar" +-- @return the program path, the tool name +-- function _instance:tool(toolkind) -- we cannot get tool in on_load, because target:toolchains() has been not checked in configuration stage. if not self._LOADED_AFTER then diff --git a/xmake/core/tool/builder.lua b/xmake/core/tool/builder.lua index e6c649580..a91b24ede 100644 --- a/xmake/core/tool/builder.lua +++ b/xmake/core/tool/builder.lua @@ -753,47 +753,81 @@ function builder:_preprocess_flags(flags) return results end --- get the target +-- get the associated target +-- +-- @return the target instance +-- function builder:target() return self._TARGET end --- get tool name +-- get the tool name, e.g. "gcc", "clang", "cl" +-- +-- @return the tool name string +-- function builder:name() return self:_tool():name() end --- get tool kind +-- get the tool kind, e.g. "cc", "cxx", "ld", "ar" +-- +-- @return the tool kind string +-- function builder:kind() return self:_tool():kind() end --- get tool program +-- get the tool program path +-- +-- @return the program path string +-- function builder:program() return self:_tool():program() end --- get toolchain of this tool +-- get the toolchain of this tool +-- +-- @return the toolchain instance +-- function builder:toolchain() return self:_tool():toolchain() end --- get the run environments +-- get the run environments for this tool +-- +-- @return the environments table +-- function builder:runenvs() return self:_tool():runenvs() end -- get properties of the tool +-- +-- @param name the property name +-- @return the property value +-- function builder:get(name) return self:_tool():get(name) end --- has flags? +-- check if the tool supports the given flags +-- +-- @param flags the flags to check +-- @param flagkind the flag kind (optional) +-- @param opt the options (optional) +-- @return true if supported +-- function builder:has_flags(flags, flagkind, opt) return self:_tool():has_flags(flags, flagkind, opt) end --- map flags from name and values, e.g. linkdirs, links, defines +-- map abstract flags to tool-specific flags +-- +-- @param name the flag category, e.g. "links", "defines", "includedirs" +-- @param values the values to map +-- @param opt the options (optional) +-- @return the mapped flags array +-- function builder:map_flags(name, values, opt) local flags = {} local mapper = self:_tool()["nf_" .. name] diff --git a/xmake/core/tool/toolchain.lua b/xmake/core/tool/toolchain.lua index 5ca360492..1491f34f3 100644 --- a/xmake/core/tool/toolchain.lua +++ b/xmake/core/tool/toolchain.lua @@ -79,6 +79,9 @@ function _instance.new(name, info, opt) end -- get toolchain name +-- +-- @return the toolchain name string +-- function _instance:name() return self._NAME end @@ -109,7 +112,10 @@ function _instance:memcache() return cache end --- get toolchain platform +-- get toolchain platform, e.g. "windows", "linux", "macosx" +-- +-- @return the platform name +-- function _instance:plat() return self._PLAT or self:config("plat") end @@ -119,7 +125,10 @@ function _instance:plat_set(plat) self._PLAT = plat end --- get toolchain architecture +-- get toolchain architecture, e.g. "x86_64", "arm64" +-- +-- @return the architecture name +-- function _instance:arch() return self._ARCH or self:config("arch") end @@ -234,6 +243,9 @@ function _instance:is_builtin() end -- get the run environments +-- +-- @return the run environments table {PATH = "...", ...} +-- function _instance:runenvs() local runenvs = self._RUNENVS if runenvs == nil then @@ -254,6 +266,10 @@ function _instance:runenvs() end -- get the program and name of the given tool kind +-- +-- @param toolkind the tool kind, e.g. "cc", "cxx", "ld", "ar" +-- @return the program path, the tool name +-- function _instance:tool(toolkind) if not self:_is_checked() then utils.warning("we cannot get tool(%s) in toolchain(%s) with %s/%s, because it has been not checked yet!", toolkind, self:name(), self:plat(), self:arch()) @@ -282,7 +298,10 @@ function _instance:cross() return self:config("cross") or config.get("cross") or self:info():get("cross") end --- get the bin directory +-- get the toolchain bin directory +-- +-- @return the bin directory path +-- function _instance:bindir() local bindir = self:config("bindir") or config.get("bin") or self:info():get("bindir") if not bindir and self:sdkdir() and os.isdir(path.join(self:sdkdir(), "bin")) then @@ -291,7 +310,10 @@ function _instance:bindir() return bindir end --- get the sdk directory +-- get the toolchain sdk directory +-- +-- @return the sdk directory path +-- function _instance:sdkdir() return self:config("sdkdir") or config.get("sdk") or self:info():get("sdkdir") end @@ -301,12 +323,20 @@ function _instance:cachekey() return self._CACHEKEY end --- get user config from `set_toolchains("", {configs = {vs = "2018"}})` +-- get toolchain config value +-- +-- @param name the config name, e.g. "sdkver", "vs" +-- @return the config value +-- function _instance:config(name) return self._CONFIGS[name] end --- set user config +-- set toolchain config value +-- +-- @param name the config name +-- @param data the config value +-- function _instance:config_set(name, data) self._CONFIGS[name] = data end @@ -317,6 +347,9 @@ function _instance:configs_save() end -- do check, we only check it once for all architectures +-- +-- @return true if the toolchain is available +-- function _instance:check() local checked = self:config("__checked") if checked == nil then diff --git a/xmake/modules/core/project/depend.lua b/xmake/modules/core/project/depend.lua index 71e50a56a..511e6fde6 100644 --- a/xmake/modules/core/project/depend.lua +++ b/xmake/modules/core/project/depend.lua @@ -96,11 +96,21 @@ function save(dependinfo, dependfile) io.save(dependfile, dependinfo) end --- Is the dependent info changed? +-- is the dependent info changed? -- --- if not depend.is_changed(dependinfo, {filemtime = os.mtime(objectfile), values = {...}}) then +-- @param dependinfo the depend info table from depend.load() +-- @param opt the options +-- - lastmtime: the last modification time to compare +-- - values: the depend values to compare +-- - files: the depend files (optional, from dependinfo.files) +-- - timecache: enable time cache for performance (optional) +-- @return true if changed +-- +-- @code +-- if not depend.is_changed(dependinfo, {lastmtime = os.mtime(objectfile), values = {program, flags}}) then -- return -- end +-- @endcode -- function is_changed(dependinfo, opt) @@ -185,23 +195,21 @@ function is_changed(dependinfo, opt) end end --- on changed for the dependent files and values +-- run callback only when dependent files or values have changed -- --- e.g. +-- @param callback the callback function to run when changed +-- @param opt the options +-- - dependfile: the depend cache file path (required) +-- - files: the source files to track +-- - values: the values to track (e.g. flags, program) -- +-- @code -- depend.on_changed(function () --- -- do some thing --- -- .. --- --- -- maybe need update dependent files --- dependinfo.files = {""} --- --- -- return new dependinfo (optional) --- return {files = {}, ..} --- --- end, {dependfile = "/xx/xx", --- values = {compinst:program(), compflags}, --- files = {sourcefile, ...}}) +-- -- do build work here +-- end, {dependfile = target:dependfile(objectfile), +-- files = {sourcefile}, +-- values = {compinst:program(), compflags}}) +-- @endcode -- function on_changed(callback, opt) opt = opt or {} diff --git a/xmake/modules/detect/sdks/find_cross_toolchain.lua b/xmake/modules/detect/sdks/find_cross_toolchain.lua index 9b7076201..e4acdfa3e 100644 --- a/xmake/modules/detect/sdks/find_cross_toolchain.lua +++ b/xmake/modules/detect/sdks/find_cross_toolchain.lua @@ -74,6 +74,12 @@ end -- -- @endcode -- +-- find cross-compilation toolchain +-- +-- @param sdkdir the SDK directory +-- @param opt the options, e.g. {bindir = "", cross = "arm-linux-gnueabihf-"} +-- @return the toolchain info table {sdkdir, bindir, cross, ...} +-- function main(sdkdir, opt) -- init arguments diff --git a/xmake/modules/detect/sdks/find_cuda.lua b/xmake/modules/detect/sdks/find_cuda.lua index 5a90cc581..0f5887313 100644 --- a/xmake/modules/detect/sdks/find_cuda.lua +++ b/xmake/modules/detect/sdks/find_cuda.lua @@ -158,6 +158,12 @@ end -- -- @endcode -- +-- find CUDA SDK +-- +-- @param sdkdir the CUDA SDK directory (optional) +-- @param opt the options, e.g. {verbose = true, force = false} +-- @return the SDK info table {sdkdir, bindir, libdirs, includedirs, ...} +-- function main(sdkdir, opt) -- init arguments diff --git a/xmake/modules/detect/sdks/find_mingw.lua b/xmake/modules/detect/sdks/find_mingw.lua index bdf97983f..69084f5e4 100644 --- a/xmake/modules/detect/sdks/find_mingw.lua +++ b/xmake/modules/detect/sdks/find_mingw.lua @@ -131,6 +131,12 @@ end -- -- @endcode -- +-- find MinGW SDK +-- +-- @param sdkdir the MinGW SDK directory (optional) +-- @param opt the options, e.g. {verbose = true, force = false} +-- @return the SDK info table {sdkdir, bindir, cross, ...} +-- function main(sdkdir, opt) opt = opt or {} diff --git a/xmake/modules/detect/sdks/find_ndk.lua b/xmake/modules/detect/sdks/find_ndk.lua index 628a76c41..ce7a4b712 100644 --- a/xmake/modules/detect/sdks/find_ndk.lua +++ b/xmake/modules/detect/sdks/find_ndk.lua @@ -275,6 +275,12 @@ end -- -- @endcode -- +-- find Android NDK SDK +-- +-- @param sdkdir the NDK SDK directory (optional) +-- @param opt the options, e.g. {verbose = true, force = false} +-- @return the SDK info table {sdkdir, bindir, cross, sdkver, ...} +-- function main(sdkdir, opt) -- init arguments diff --git a/xmake/modules/detect/sdks/find_qt.lua b/xmake/modules/detect/sdks/find_qt.lua index a7aa8e57c..c40491948 100644 --- a/xmake/modules/detect/sdks/find_qt.lua +++ b/xmake/modules/detect/sdks/find_qt.lua @@ -333,6 +333,12 @@ end -- -- @endcode -- +-- find Qt SDK +-- +-- @param sdkdir the Qt SDK directory (optional) +-- @param opt the options, e.g. {verbose = true, force = false} +-- @return the SDK info table {sdkdir, bindir, libdir, includedir, ...} +-- function main(sdkdir, opt) -- init arguments diff --git a/xmake/modules/detect/sdks/find_vcpkgdir.lua b/xmake/modules/detect/sdks/find_vcpkgdir.lua index 0b1103c8d..0b504b1c8 100644 --- a/xmake/modules/detect/sdks/find_vcpkgdir.lua +++ b/xmake/modules/detect/sdks/find_vcpkgdir.lua @@ -26,6 +26,10 @@ import("core.cache.detectcache") import("lib.detect.find_tool") -- find vcpkgdir +-- find the vcpkg installation directory +-- +-- @return the vcpkg directory path, or nil +-- function main() local vcpkgdir = detectcache:get("detect.sdks.find_vcpkgdir") if vcpkgdir == nil then diff --git a/xmake/modules/lib/detect/check_bigendian.lua b/xmake/modules/lib/detect/check_bigendian.lua index 8de9b99ac..82948493f 100644 --- a/xmake/modules/lib/detect/check_bigendian.lua +++ b/xmake/modules/lib/detect/check_bigendian.lua @@ -61,6 +61,11 @@ end -- local is_bigendian = check_bigendian() -- @endcode -- +-- check if the target system is big-endian +-- +-- @param opt the options, e.g. {target = target} +-- @return true if big-endian +-- function main(opt) local snippets = check_bigendian_template local ok, is_bigendian = check_cxxsnippets(snippets, table.join(table.wrap(opt), {binary_match = _byteorder_binary_match})) diff --git a/xmake/modules/lib/detect/check_csnippets.lua b/xmake/modules/lib/detect/check_csnippets.lua index a44e2c4d5..ea46686a4 100644 --- a/xmake/modules/lib/detect/check_csnippets.lua +++ b/xmake/modules/lib/detect/check_csnippets.lua @@ -44,6 +44,12 @@ import("lib.detect.check_cxsnippets") -- local ok = check_csnippets({snippet_name = "void test(){}", "#define TEST 1"}, {types = "wchar_t", includes = "stdio.h"}) -- @endcode -- +-- check C code snippets for compilation +-- +-- @param snippets the code snippets table +-- @param opt the options, e.g. {target = target, includes = {}, configs = {}} +-- @return true and output on success, or false +-- function main(snippets, opt) return check_cxsnippets(snippets, table.join(table.wrap(opt), {sourcekind = "cc"})) end diff --git a/xmake/modules/lib/detect/check_cxsnippets.lua b/xmake/modules/lib/detect/check_cxsnippets.lua index ad0310082..1e7dc604b 100644 --- a/xmake/modules/lib/detect/check_cxsnippets.lua +++ b/xmake/modules/lib/detect/check_cxsnippets.lua @@ -171,6 +171,12 @@ end -- }]], {tryrun = true}) -- @endcode -- +-- check C/C++ code snippets for compilation +-- +-- @param snippets the code snippets table +-- @param opt the options, e.g. {target = target, sourcekind = "cc", includes = {}, configs = {}} +-- @return true and output on success, or false +-- function main(snippets, opt) -- init options diff --git a/xmake/modules/lib/detect/check_cxxsnippets.lua b/xmake/modules/lib/detect/check_cxxsnippets.lua index 785569181..c463b50ff 100644 --- a/xmake/modules/lib/detect/check_cxxsnippets.lua +++ b/xmake/modules/lib/detect/check_cxxsnippets.lua @@ -44,6 +44,12 @@ import("lib.detect.check_cxsnippets") -- local ok = check_cxxsnippets({snippet_name = "void test(){}", "#define TEST 1"}, {types = "wchar_t", includes = "stdio.h"}) -- @endcode -- +-- check C++ code snippets for compilation +-- +-- @param snippets the code snippets table +-- @param opt the options, e.g. {target = target, includes = {}, configs = {}} +-- @return true and output on success, or false +-- function main(snippets, opt) return check_cxsnippets(snippets, table.join(table.wrap(opt), {sourcekind = "cxx"})) end diff --git a/xmake/modules/lib/detect/check_sizeof.lua b/xmake/modules/lib/detect/check_sizeof.lua index d6176b69a..ffd9dfcd9 100644 --- a/xmake/modules/lib/detect/check_sizeof.lua +++ b/xmake/modules/lib/detect/check_sizeof.lua @@ -63,6 +63,12 @@ end -- local size = check_sizeof("std::string", {includes = "string"}) -- @endcode -- +-- check the size of a C/C++ type +-- +-- @param typename the type name, e.g. "int", "size_t" +-- @param opt the options, e.g. {includes = {"stddef.h"}, target = target} +-- @return the type size in bytes, or -1 +-- function main(typename, opt) local snippets = check_sizeof_template:gsub('${TYPE}', typename) local ok, size = check_cxxsnippets(snippets, table.join(table.wrap(opt), {binary_match = _binary_match})) diff --git a/xmake/modules/lib/detect/features.lua b/xmake/modules/lib/detect/features.lua index 997acd2a1..4f0463181 100644 --- a/xmake/modules/lib/detect/features.lua +++ b/xmake/modules/lib/detect/features.lua @@ -35,6 +35,12 @@ import("core.base.scheduler") -- local features = features("clang", {flags = {"-g", "-O0"}, envs = {PATH = ""}}) -- @endcode -- +-- get all supported features of the given tool +-- +-- @param name the tool name, e.g. "clang", "gcc" +-- @param opt the options, e.g. {program = "", flags = {}} +-- @return the features table, e.g. {cxx_constexpr = true} +-- function main(name, opt) -- init options diff --git a/xmake/modules/lib/detect/find_package.lua b/xmake/modules/lib/detect/find_package.lua index eedce1cec..3c53a3ca9 100644 --- a/xmake/modules/lib/detect/find_package.lua +++ b/xmake/modules/lib/detect/find_package.lua @@ -48,6 +48,12 @@ import("private.utils.package", {alias = "package_utils"}) -- -- @endcode -- +-- find package from system or package managers +-- +-- @param name the package name +-- @param opt the options, e.g. {require_version = ">=1.0", system = true, packagedirs = {}} +-- @return the package info table {links, linkdirs, includedirs, ...}, or nil +-- function main(name, opt) -- get the copied options diff --git a/xmake/modules/net/fasturl.lua b/xmake/modules/net/fasturl.lua index ff36805e1..90a9cd27c 100644 --- a/xmake/modules/net/fasturl.lua +++ b/xmake/modules/net/fasturl.lua @@ -29,6 +29,10 @@ function _parse_host(url) return host end +-- add urls to the ping queue for later sorting +-- +-- @param urls the urls array to add +-- function add(urls) local pinginfo = _g._PINGINFO or {} _g._PINGHOSTS = _g._PINGHOSTS or {} @@ -40,6 +44,11 @@ function add(urls) end end +-- sort urls by network latency (fastest first) +-- +-- @param urls the urls array to sort +-- @return the sorted urls array +-- function sort(urls) -- ping hosts diff --git a/xmake/modules/net/proxy.lua b/xmake/modules/net/proxy.lua index 812fdc536..1ab9779e6 100644 --- a/xmake/modules/net/proxy.lua +++ b/xmake/modules/net/proxy.lua @@ -93,7 +93,11 @@ function _is_callable(func) end end --- get proxy mirror url +-- get proxy mirror url for the given url +-- +-- @param url the original url +-- @return the mirrored url +-- function mirror(url) local proxy_pac = _proxy_pac() if proxy_pac and proxy_pac.mirror then @@ -142,8 +146,10 @@ function _global_proxy() return proxy end --- get proxy configuration from the given url, [protocol://]host[:port] +-- get proxy configuration for the given url -- +-- @param url the target url +-- @return the proxy string, e.g. "socks5://127.0.0.1:1080", or nil -- @see https://github.com/xmake-io/xmake/issues/854 -- function config(url) diff --git a/xmake/modules/package/manager/find_package.lua b/xmake/modules/package/manager/find_package.lua index f6209c453..b90e584f4 100644 --- a/xmake/modules/package/manager/find_package.lua +++ b/xmake/modules/package/manager/find_package.lua @@ -169,6 +169,18 @@ end -- @endcode -- +-- find package from package managers (vcpkg, conan, brew, apt, etc.) +-- +-- @param name the package name +-- @param opt the options, e.g. {packagedirs = {}, system = true} +-- @return the package info table, or nil +-- +-- find package from package managers (vcpkg, conan, brew, apt, etc.) +-- +-- @param name the package name +-- @param opt the options, e.g. {packagedirs = {}, system = true} +-- @return the package info table, or nil +-- function main(name, opt) -- get the copied options diff --git a/xmake/modules/private/action/build/build_binary.lua b/xmake/modules/private/action/build/build_binary.lua index 47884fd44..e53d6525a 100644 --- a/xmake/modules/private/action/build/build_binary.lua +++ b/xmake/modules/private/action/build/build_binary.lua @@ -22,6 +22,12 @@ import("build_object") import("private.action.build.target", {alias = "target_buildutils"}) +-- build binary target +-- +-- @param jobgraph the job graph for dependency tracking +-- @param target the target instance +-- @param opt the options +-- function main(jobgraph, target, opt) opt = opt or {} local objects_group = target:fullname() .. "/objects" diff --git a/xmake/modules/private/action/build/build_moduleonly.lua b/xmake/modules/private/action/build/build_moduleonly.lua index e13693cab..bbaa8a079 100644 --- a/xmake/modules/private/action/build/build_moduleonly.lua +++ b/xmake/modules/private/action/build/build_moduleonly.lua @@ -21,6 +21,12 @@ -- imports import("build_object") +-- build module-only target +-- +-- @param jobgraph the job graph for dependency tracking +-- @param target the target instance +-- @param opt the options +-- function main(jobgraph, target, opt) build_object(jobgraph, target, opt) end diff --git a/xmake/modules/private/action/build/build_object.lua b/xmake/modules/private/action/build/build_object.lua index 1b5a26c72..2f48b730e 100644 --- a/xmake/modules/private/action/build/build_object.lua +++ b/xmake/modules/private/action/build/build_object.lua @@ -21,6 +21,12 @@ -- imports import("private.action.build.target", {alias = "target_buildutils"}) +-- build object files target +-- +-- @param jobgraph the job graph for dependency tracking +-- @param target the target instance +-- @param opt the options +-- function main(jobgraph, target, opt) target_buildutils.add_filejobs(jobgraph, target, opt) end diff --git a/xmake/modules/private/action/build/build_shared.lua b/xmake/modules/private/action/build/build_shared.lua index 95aa3800c..11f2e2e17 100644 --- a/xmake/modules/private/action/build/build_shared.lua +++ b/xmake/modules/private/action/build/build_shared.lua @@ -21,6 +21,12 @@ -- imports import("build_binary") +-- build shared library target +-- +-- @param jobgraph the job graph for dependency tracking +-- @param target the target instance +-- @param opt the options +-- function main(jobgraph, target, opt) build_binary(jobgraph, target, opt) end diff --git a/xmake/modules/private/action/build/build_static.lua b/xmake/modules/private/action/build/build_static.lua index 028b83fbf..929640acb 100644 --- a/xmake/modules/private/action/build/build_static.lua +++ b/xmake/modules/private/action/build/build_static.lua @@ -21,6 +21,12 @@ -- imports import("build_binary") +-- build static library target +-- +-- @param jobgraph the job graph for dependency tracking +-- @param target the target instance +-- @param opt the options +-- function main(jobgraph, target, opt) build_binary(jobgraph, target, opt) end diff --git a/xmake/modules/private/action/build/link_objects.lua b/xmake/modules/private/action/build/link_objects.lua index 54d03da09..f2fede1ec 100644 --- a/xmake/modules/private/action/build/link_objects.lua +++ b/xmake/modules/private/action/build/link_objects.lua @@ -61,6 +61,12 @@ function _do_link_target(target, opt) values = depvalues, files = depfiles, dryrun = dryrun}) end +-- link object files to the target file +-- +-- @param jobgraph the job graph for dependency tracking +-- @param target the target instance +-- @param opt the options +-- function main(jobgraph, target, opt) opt = opt or {} local buildcmds = opt.buildcmds diff --git a/xmake/modules/private/action/build/object.lua b/xmake/modules/private/action/build/object.lua index 837c5fec4..7b9d4afee 100644 --- a/xmake/modules/private/action/build/object.lua +++ b/xmake/modules/private/action/build/object.lua @@ -171,6 +171,13 @@ function _add_jobgraph(target, jobgraph, sourcebatch, opt) end end +-- build object files from source batch +-- +-- @param target the target instance +-- @param jobgraph the job graph for dependency tracking +-- @param sourcebatch the source batch {sourcefiles, sourcekind, ...} +-- @param opt the options, e.g. {progress = {}} +-- function main(target, jobgraph, sourcebatch, opt) opt = opt or {} if jobgraph.add_orders then diff --git a/xmake/modules/private/action/build/prepare_files.lua b/xmake/modules/private/action/build/prepare_files.lua index 0b37b5305..af7bf1a83 100644 --- a/xmake/modules/private/action/build/prepare_files.lua +++ b/xmake/modules/private/action/build/prepare_files.lua @@ -22,6 +22,12 @@ import("core.base.option") import("private.action.build.target", {alias = "target_buildutils"}) +-- prepare source files for building +-- +-- @param jobgraph the job graph for dependency tracking +-- @param target the target instance +-- @param opt the options +-- function main(jobgraph, target, opt) target_buildutils.add_filejobs(jobgraph, target, opt) end diff --git a/xmake/modules/private/action/require/impl/actions/check.lua b/xmake/modules/private/action/require/impl/actions/check.lua index d6143fcfa..2bd840d75 100644 --- a/xmake/modules/private/action/require/impl/actions/check.lua +++ b/xmake/modules/private/action/require/impl/actions/check.lua @@ -22,7 +22,11 @@ import("core.base.option") import("core.project.config") --- check the given package +-- check the package after installation +-- +-- @param package the package instance +-- @param opt the options +-- function main(package, opt) opt = opt or {} diff --git a/xmake/modules/private/action/require/impl/actions/download.lua b/xmake/modules/private/action/require/impl/actions/download.lua index 84c8d85be..5930b3cbb 100644 --- a/xmake/modules/private/action/require/impl/actions/download.lua +++ b/xmake/modules/private/action/require/impl/actions/download.lua @@ -323,6 +323,16 @@ function _urls(package) end -- download the given package +-- download the package source +-- +-- @param package the package instance +-- @param opt the options +-- +-- download the package source +-- +-- @param package the package instance +-- @param opt the options +-- function main(package, opt) opt = opt or {} diff --git a/xmake/modules/private/action/require/impl/actions/download_resources.lua b/xmake/modules/private/action/require/impl/actions/download_resources.lua index 30e7f9146..c185d25b0 100644 --- a/xmake/modules/private/action/require/impl/actions/download_resources.lua +++ b/xmake/modules/private/action/require/impl/actions/download_resources.lua @@ -164,6 +164,14 @@ function _download(package, resource_name, resource_url, resource_hash) end -- download all resources of the given package +-- download the package resources +-- +-- @param package the package instance +-- +-- download the package resources +-- +-- @param package the package instance +-- function main(package) -- we don't need to download it if we use the precompiled artifacts to install package diff --git a/xmake/modules/private/action/require/impl/actions/install.lua b/xmake/modules/private/action/require/impl/actions/install.lua index 94f8007b3..3789573b6 100644 --- a/xmake/modules/private/action/require/impl/actions/install.lua +++ b/xmake/modules/private/action/require/impl/actions/install.lua @@ -436,6 +436,10 @@ function _get_package_tipname(package) return package_tipname end +-- install the package +-- +-- @param package the package instance +-- function main(package) local oldir = _enter_workdir(package) diff --git a/xmake/modules/private/action/require/impl/actions/patch_sources.lua b/xmake/modules/private/action/require/impl/actions/patch_sources.lua index 81f506420..6c18b69b1 100644 --- a/xmake/modules/private/action/require/impl/actions/patch_sources.lua +++ b/xmake/modules/private/action/require/impl/actions/patch_sources.lua @@ -143,6 +143,14 @@ function _patch(package, patchinfo) end -- patch the given package +-- patch the package sources +-- +-- @param package the package instance +-- +-- patch the package sources +-- +-- @param package the package instance +-- function main(package) -- we don't need to patch it if we use the precompiled artifacts to install package diff --git a/xmake/modules/private/action/require/impl/actions/test.lua b/xmake/modules/private/action/require/impl/actions/test.lua index f30d5febe..d07e5ece3 100644 --- a/xmake/modules/private/action/require/impl/actions/test.lua +++ b/xmake/modules/private/action/require/impl/actions/test.lua @@ -23,6 +23,14 @@ import("core.base.option") import("private.action.require.impl.utils.filter") -- test the given package +-- test the installed package +-- +-- @param package the package instance +-- +-- test the installed package +-- +-- @param package the package instance +-- function main(package) -- enter the test directory diff --git a/xmake/modules/private/action/require/impl/download_packages.lua b/xmake/modules/private/action/require/impl/download_packages.lua index b25038672..81bbdd074 100644 --- a/xmake/modules/private/action/require/impl/download_packages.lua +++ b/xmake/modules/private/action/require/impl/download_packages.lua @@ -232,6 +232,11 @@ function _download_packages(packages_download) end -- download packages +-- download all required packages +-- +-- @param requires the requires table +-- @param opt the options +-- function main(requires, opt) opt = opt or {} diff --git a/xmake/modules/private/action/require/impl/export_packages.lua b/xmake/modules/private/action/require/impl/export_packages.lua index ee62efc4b..b4141a7e6 100644 --- a/xmake/modules/private/action/require/impl/export_packages.lua +++ b/xmake/modules/private/action/require/impl/export_packages.lua @@ -23,6 +23,11 @@ import("core.package.package", {alias = "core_package"}) import("private.action.require.impl.package") -- export packages +-- export required packages to a directory +-- +-- @param requires the requires table +-- @param opt the options +-- function main(requires, opt) opt = opt or {} local packages = {} diff --git a/xmake/modules/private/action/require/impl/import_packages.lua b/xmake/modules/private/action/require/impl/import_packages.lua index 1d11e1a06..134cf63bd 100644 --- a/xmake/modules/private/action/require/impl/import_packages.lua +++ b/xmake/modules/private/action/require/impl/import_packages.lua @@ -23,6 +23,11 @@ import("core.package.package", {alias = "core_package"}) import("private.action.require.impl.package") -- import packages +-- import packages from an exported directory +-- +-- @param requires the requires table +-- @param opt the options +-- function main(requires, opt) opt = opt or {} local packages = {} diff --git a/xmake/modules/private/action/require/impl/install_packages.lua b/xmake/modules/private/action/require/impl/install_packages.lua index 359f9ac47..bd7d59606 100644 --- a/xmake/modules/private/action/require/impl/install_packages.lua +++ b/xmake/modules/private/action/require/impl/install_packages.lua @@ -843,6 +843,11 @@ function _install_packages(requires, opt) return packages end +-- install all required packages +-- +-- @param requires the requires table +-- @param opt the options +-- function main(requires, opt) -- we need to install toolchain packages first, -- because we will call compiler-specific api in package.on_load, diff --git a/xmake/modules/private/action/require/impl/lock_packages.lua b/xmake/modules/private/action/require/impl/lock_packages.lua index 61cc19a85..4609146b7 100644 --- a/xmake/modules/private/action/require/impl/lock_packages.lua +++ b/xmake/modules/private/action/require/impl/lock_packages.lua @@ -48,6 +48,10 @@ function _lock_package(instance) end -- lock all required packages +-- lock package versions +-- +-- @param packages the packages table +-- function main(packages) if project.policy("package.requires_lock") then local plat = config.plat() or os.subhost() diff --git a/xmake/modules/private/action/require/impl/register_packages.lua b/xmake/modules/private/action/require/impl/register_packages.lua index e06f9d5cb..94d93b523 100644 --- a/xmake/modules/private/action/require/impl/register_packages.lua +++ b/xmake/modules/private/action/require/impl/register_packages.lua @@ -133,6 +133,10 @@ function _register_required_package(instance, required_package) end -- register all required root packages to local cache +-- register all packages to targets +-- +-- @param packages the packages table +-- function main(packages) -- register to package cache for add_packages() diff --git a/xmake/modules/private/action/require/impl/search_packages.lua b/xmake/modules/private/action/require/impl/search_packages.lua index f8195afcb..38c4f05a1 100644 --- a/xmake/modules/private/action/require/impl/search_packages.lua +++ b/xmake/modules/private/action/require/impl/search_packages.lua @@ -40,6 +40,11 @@ function _search_packages(name, opt) end -- search packages +-- search packages by names +-- +-- @param names the package names to search +-- @param opt the options +-- function main(names, opt) local results = {} for _, name in ipairs(names) do diff --git a/xmake/modules/private/action/require/impl/uninstall_packages.lua b/xmake/modules/private/action/require/impl/uninstall_packages.lua index a51c3b05f..685b5c973 100644 --- a/xmake/modules/private/action/require/impl/uninstall_packages.lua +++ b/xmake/modules/private/action/require/impl/uninstall_packages.lua @@ -23,6 +23,11 @@ import("core.cache.localcache") import("private.action.require.impl.package") -- uninstall packages +-- uninstall required packages +-- +-- @param requires the requires table +-- @param opt the options +-- function main(requires, opt) -- init options diff --git a/xmake/modules/private/utils/batchcmds.lua b/xmake/modules/private/utils/batchcmds.lua index 378f4f0f5..3f584b286 100644 --- a/xmake/modules/private/utils/batchcmds.lua +++ b/xmake/modules/private/utils/batchcmds.lua @@ -249,22 +249,38 @@ function _runcmds(cmds, opt) end end --- is empty? no commands +-- is empty? (no pending commands) +-- +-- @return true if no commands +-- function batchcmds:empty() return #self:cmds() == 0 end --- get commands +-- get all pending commands +-- +-- @return the commands array +-- function batchcmds:cmds() return self._CMDS end --- add command: os.runv +-- add command: run program silently +-- +-- @param program the program path +-- @param argv the arguments (optional) +-- @param opt the options, e.g. {envs = {}} +-- function batchcmds:runv(program, argv, opt) table.insert(self:cmds(), {kind = "runv", program = program, argv = argv, opt = opt}) end --- add command: os.vrunv +-- add command: run program with verbose output +-- +-- @param program the program path +-- @param argv the arguments (optional) +-- @param opt the options, e.g. {envs = {}} +-- function batchcmds:vrunv(program, argv, opt) table.insert(self:cmds(), {kind = "vrunv", program = program, argv = argv, opt = opt}) end @@ -279,7 +295,12 @@ function batchcmds:vexecv(program, argv, opt) table.insert(self:cmds(), {kind = "vexecv", program = program, argv = argv, opt = opt}) end --- add command: run lua script file, command or module +-- add command: run lua script +-- +-- @param script the lua script path or module name +-- @param argv the arguments (optional) +-- @param opt the options (optional) +-- function batchcmds:lua(script, argv, opt) table.insert(self:cmds(), {kind = "lua", script = script, argv = argv, opt = opt}) end @@ -289,7 +310,12 @@ function batchcmds:vlua(script, argv, opt) table.insert(self:cmds(), {kind = "vlua", script = script, argv = argv, opt = opt}) end --- add command: compiler.compile +-- add command: compile source files +-- +-- @param sourcefiles the source file paths +-- @param objectfile the output object file path +-- @param opt the options, e.g. {sourcekind = "cxx", configs = {}} +-- function batchcmds:compile(sourcefiles, objectfile, opt) -- bind target if exists @@ -365,7 +391,12 @@ function batchcmds:compilev(argv, opt) end end --- add command: linker.link +-- add command: link object files +-- +-- @param objectfiles the object file paths +-- @param targetfile the output target file path +-- @param opt the options (optional) +-- function batchcmds:link(objectfiles, targetfile, opt) -- bind target if exists @@ -406,27 +437,48 @@ function batchcmds:link(objectfiles, targetfile, opt) self:vrunv(program, argv, {envs = table.join(linker_inst:runenvs(), opt.envs)}) end --- add command: os.mkdir +-- add command: create directory +-- +-- @param dir the directory path +-- function batchcmds:mkdir(dir) table.insert(self:cmds(), {kind = "mkdir", dir = dir}) end --- add command: os.rmdir +-- add command: remove directory +-- +-- @param dir the directory path +-- @param opt the options, e.g. {emptydirs = true} +-- function batchcmds:rmdir(dir, opt) table.insert(self:cmds(), {kind = "rmdir", dir = dir, opt = opt}) end --- add command: os.rm +-- add command: remove file +-- +-- @param filepath the file path +-- @param opt the options (optional) +-- function batchcmds:rm(filepath, opt) table.insert(self:cmds(), {kind = "rm", filepath = filepath, opt = opt}) end --- add command: os.cp +-- add command: copy files or directories +-- +-- @param srcpath the source path (supports patterns) +-- @param dstpath the destination path +-- @param opt the options, e.g. {rootdir = "", symlink = true} +-- function batchcmds:cp(srcpath, dstpath, opt) table.insert(self:cmds(), {kind = "cp", srcpath = srcpath, dstpath = dstpath, opt = opt}) end --- add command: os.mv +-- add command: move files or directories +-- +-- @param srcpath the source path +-- @param dstpath the destination path +-- @param opt the options (optional) +-- function batchcmds:mv(srcpath, dstpath, opt) table.insert(self:cmds(), {kind = "mv", srcpath = srcpath, dstpath = dstpath, opt = opt}) end @@ -436,17 +488,30 @@ function batchcmds:ln(srcpath, dstpath, opt) table.insert(self:cmds(), {kind = "ln", srcpath = srcpath, dstpath = dstpath, opt = opt}) end --- add command: os.cd +-- add command: change directory +-- +-- @param dir the directory path +-- @param opt the options (optional) +-- function batchcmds:cd(dir, opt) table.insert(self:cmds(), {kind = "cd", dir = dir, opt = opt}) end --- add command: show +-- add command: show message +-- +-- @param format the format string +-- @param ... the format arguments +-- function batchcmds:show(format, ...) table.insert(self:cmds(), {kind = "show", format = format, argv = table.pack(...)}) end --- add command: show progress +-- add command: show message with progress +-- +-- @param progress the progress value (0 ~ 100) +-- @param format the format string with color markup +-- @param ... the format arguments +-- function batchcmds:show_progress(progress, format, ...) table.insert(self:cmds(), {kind = "show_progress", progress = progress, format = format, argv = table.pack(...)}) end @@ -472,6 +537,10 @@ function batchcmds:change_rpath(filepath, rpath_old, rpath_new, opt) end -- add raw command for the specific generator or xpack format +-- +-- @param kind the command kind +-- @param rawstr the raw command string +-- function batchcmds:rawcmd(kind, rawstr) table.insert(self:cmds(), {kind = kind, rawstr = rawstr}) end @@ -481,7 +550,10 @@ function batchcmds:depinfo() return self._DEPINFO end --- add dependent files +-- add dependent files for incremental build +-- +-- @param ... the dependent file paths +-- function batchcmds:add_depfiles(...) local depinfo = self._DEPINFO or {} depinfo.files = depinfo.files or {} @@ -497,14 +569,20 @@ function batchcmds:add_depvalues(...) self._DEPINFO = depinfo end --- set the last mtime of dependent files and values +-- set the last modification time for dependency checking +-- +-- @param lastmtime the last modification time +-- function batchcmds:set_depmtime(lastmtime) local depinfo = self._DEPINFO or {} depinfo.lastmtime = lastmtime self._DEPINFO = depinfo end --- set cache file of depend info +-- set the cache file path for dependency info +-- +-- @param cachefile the dependency cache file path +-- function batchcmds:set_depcache(cachefile) local depinfo = self._DEPINFO or {} depinfo.dependfile = cachefile diff --git a/xmake/modules/private/utils/target.lua b/xmake/modules/private/utils/target.lua index 56fb6faeb..217daad52 100644 --- a/xmake/modules/private/utils/target.lua +++ b/xmake/modules/private/utils/target.lua @@ -26,6 +26,12 @@ import("core.project.project") import("utils.binary.deplibs", {alias = "get_depend_libraries"}) -- Is this target has these tools? +-- check if the given tool is in the tools list +-- +-- @param toolname the tool name to check +-- @param tools the tools table +-- @return true if found +-- function has_tool(toolname, tools) if toolname then -- We need compatibility with gcc/g++, clang/clang++ for c++ compiler/linker @@ -56,6 +62,13 @@ end -- only for clang: add_cxxflags("clang::-stdlib=libc++") -- only for clang and multiple flags: add_cxxflags("-stdlib=libc++", "-DFOO", {tools = "clang"}) -- +-- check if a flag belongs to the given tool +-- +-- @param flag the flag string +-- @param toolinst the tool instance +-- @param extraconf the extra configuration +-- @return the flag if belongs, or nil +-- function flag_belong_to_tool(flag, toolinst, extraconf) local for_this_tool = true local flagconf = extraconf and extraconf[flag] @@ -122,6 +135,10 @@ function translate_flags_in_tool(target, flagkind, flags) end -- get project targets +-- get all enabled project targets +-- +-- @return the targets array +-- function get_project_targets() local selected_target = option.get("target") if selected_target then @@ -169,6 +186,11 @@ function check_target_toolchains() end -- config target +-- configure the given target (run on_config rules) +-- +-- @param target the target instance +-- @param opt the options (optional) +-- function config_target(target, opt) for _, rule in ipairs(table.wrap(target:orderules())) do local before_config = rule:script("config_before") @@ -197,6 +219,10 @@ function config_target(target, opt) end -- config targets +-- configure all project targets +-- +-- @param opt the options (optional) +-- function config_targets(opt) opt = opt or {} for _, target in ipairs(table.wrap(project.ordertargets())) do diff --git a/xmake/modules/target/action/install/cmake_importfiles.lua b/xmake/modules/target/action/install/cmake_importfiles.lua index c9c454554..4fc38a5aa 100644 --- a/xmake/modules/target/action/install/cmake_importfiles.lua +++ b/xmake/modules/target/action/install/cmake_importfiles.lua @@ -166,7 +166,11 @@ function _install_cmake_targetfile(target, installdir, filename, opt) end end --- install .cmake import files +-- install .cmake import files for the target +-- +-- @param target the target instance +-- @param opt the options, e.g. {installdir = "", libdir = ""} +-- function main(target, opt) -- check diff --git a/xmake/modules/target/action/install/main.lua b/xmake/modules/target/action/install/main.lua index 466ebe551..e86c63a75 100644 --- a/xmake/modules/target/action/install/main.lua +++ b/xmake/modules/target/action/install/main.lua @@ -214,6 +214,12 @@ function _install_moduleonly(target, opt) end end +-- install the given target +-- +-- @param target the target instance +-- @param opt the options, e.g. {installdir = "", libdir = "", bindir = "", includedir = "", +-- headers = true, binaries = true, libraries = true, packages = true} +-- function main(target, opt) opt = opt or {} if opt.headers == nil then diff --git a/xmake/modules/target/action/install/pkgconfig_importfiles.lua b/xmake/modules/target/action/install/pkgconfig_importfiles.lua index 9a9b8ee81..b0b91efa4 100644 --- a/xmake/modules/target/action/install/pkgconfig_importfiles.lua +++ b/xmake/modules/target/action/install/pkgconfig_importfiles.lua @@ -18,7 +18,11 @@ -- @file pkgconfig_importfiles.lua -- --- install pkgconfig/.pc import files +-- install pkgconfig/.pc import files for the target +-- +-- @param target the target instance +-- @param opt the options, e.g. {installdir = "", libdir = "", includedir = ""} +-- function main(target, opt) -- check diff --git a/xmake/modules/target/action/uninstall/main.lua b/xmake/modules/target/action/uninstall/main.lua index a81aa63d8..bae3da830 100644 --- a/xmake/modules/target/action/uninstall/main.lua +++ b/xmake/modules/target/action/uninstall/main.lua @@ -154,6 +154,11 @@ function _uninstall_moduleonly(target, opt) _uninstall_headers(target, opt) end +-- uninstall the given target +-- +-- @param target the target instance +-- @param opt the options, e.g. {installdir = "", libdir = "", bindir = "", includedir = ""} +-- function main(target, opt) opt = opt or {} local installdir = opt.installdir or target:installdir() diff --git a/xmake/modules/utils/progress.lua b/xmake/modules/utils/progress.lua index 3e7598ac2..ac9c1e8f6 100644 --- a/xmake/modules/utils/progress.lua +++ b/xmake/modules/utils/progress.lua @@ -375,15 +375,23 @@ function _get_target_name_prefix(progress) end end --- set the associated target name for the progress object (coroutine-local) --- it's safe to call with non-table progress (e.g. number), it will be ignored +-- set the associated target name for the progress display +-- +-- @param progress the progress object or number +-- @param target the target instance +-- function set_target(progress, target) if _is_show_target_enabled() and type(progress) == "table" and progress.set then progress:set("target_name", target:fullname()) end end --- show the message with progress +-- show the message with progress indicator +-- +-- @param progress the progress value (0 ~ 100) +-- @param format the format string with color markup +-- @param ... the format arguments +-- function show(progress, format, ...) local target_prefix = _get_target_name_prefix(progress) if target_prefix then @@ -403,8 +411,11 @@ function show(progress, format, ...) end end --- print additional output logs with colors outside the progress log area, such as warning logs. --- it's used when the progress style is multirow/singlerow refresh. +-- print additional output logs outside the progress area (for warnings, etc.) +-- +-- @param format the format string with color markup +-- @param ... the format arguments +-- function show_output(format, ...) local refresh_mode = _g.refresh_mode if refresh_mode == "singlerow" then @@ -502,7 +513,13 @@ function show_abort() end end --- get the message text with progress +-- get the formatted message text with progress (without printing) +-- +-- @param progress the progress value (0 ~ 100) +-- @param format the format string +-- @param ... the format arguments +-- @return the formatted text string +-- function text(progress, format, ...) local target_prefix = _get_target_name_prefix(progress) if target_prefix then |