paradoxv5 / ffi-uctags Goto Github PK

Follow up to #6.
Currently, FFI-UCtags reads variables and functions naïvely without considering the storage classifiers.

c6811ec has hot-reverted variable loading.
Only those marked with extern or (const but not static) are available via FFI.
Note that u-ctags read const as part of the type (typeref), so it might appreciate some help from #19.

Functions, while extern by default, should also exclude static ones.

如题

Requires #17.
Note the word ‘unit’ in the title – don’t do integration tests (yet?).
Therefore, no need to recursive-checkout and build the #17 submodule (which will cost the workflow an entire minute or two).

Submodule at /u-ctags/src, build (prefix) at /u-ctags.

Research on concerns:

• U-ctags is GPL-2.0, though bundling the source code verbatim and not overlapping our content with theirs complies with the copyleft.
  • This licensing is one of the reasons of why I decided against just bundling a prebuilt executable.
  • Should also double remind desktop devs about the two-part licensing – once in the “Dependency” paragraph at the top, once in the “License” section at the bottom.
• While not a Ruby extension, the .gemspec can make & make install any Makefile after executing extconf.rb.
• U-ctags dependencies are listed at autotools.rst#gnulinux-distributions. gcc, make, pkg-config, autoconf and automake needs to be checked; the rest are for disableable features. ./autogen.sh and ./configure check them
• U-ctags is a lot of files, so building it will “take a while”. The README.md should include and cite how to enable parallel make: https://build.betterup.com/one-weird-trick-that-will-speed-up-your-bundle-install#the-make-environment-variable

./configure options:

--prefix=/EXPANDED/PATH/TO/./u-ctags
--disable-readcmd
--disable-xml
--disable-json
--disable-seccomp
--disable-yaml
--disable-pcre2
--without-included-regex

The const keyword is included in the typeref of a construct. The current implementation does not recognize the prefix and falls back to pointers.

typedef alias > original name > inferred member name

May demand yet another refactor to the struct/union/enum system

This is similar to but independent from #21.

Currently, pointers to structs/unions directly are recognized for FFI::Struct#by_ref; but when a typedef is in between, it’s treated as a generic pointer, because typedefs are handled by the basic type workflow (#find_type).

• Replace puts … if $VERBOSE with a module_function
• Optional: define this method in a separate logging module which UCtags includes

u-ctags kinds f (for functions) and v (for variables)

C headers are supposed to only have declarations, though; but violations to this convention can occur, e.g., https://github.com/phoboslab/qoi/blob/dfc056e813c98d307238d35f7f041a725d699dfc/qoi.h

1. Similar to the library name arg handled by FFI, if the header arg is a relative path but the file isn’t in working directory, also check the system header directories (e.g., /usr/include, /usr/local/include and /opt/local/include)
2. If the header is not given, identify the header name from the library name and use the previous checkbox point feature to locate it.

Options to

• not import constructs with a _ prefix (would also exclude __anon constructs)
• remove a prefix (e.g., glfwInit ➡ Init)

• u-ctags kinds e and g
  • Import to Constants – reüse mechanism for structs/unions
• documentation (search for /\((and|or) enums? in future versions\)/)

attach_function :long_running_function, [], :int, blocking: true

This allows other Ruby threads (if there are any) to proceed while the current one is crunching numbers in C.

Do not set this flag for FFI::CURRENT_PROCESS libraries or headers with #include <ruby.h> (requires #5).

Example header:

typedef struct {} S;
typedef S Alias; // breaks

Array members of structs are inline.

https://ruby.github.io/rake/Rake/FileUtilsExt.html#method-i-when_writing

As the scope of the project grows, so does the risk of name collisions.

Other benefits:

• Consistent
• Fast to process

https://github.com/universal-ctags/ctags/blob/v6.0.0/docs/parser-cxx.rst#automatically-expanding-macros-defined-in-the-same-input-file-highly-experimental

These are:

• opaque structs/unions
  • e.g., struct NAME with no { … }
• Structs with a flexible array member (ffi/ffi#436)
  • Requires #14

Without knowing the members, they can only be used #by_ref until manually specifying their actual layouts.

The implementation will depend on whether u-ctags supports or will support this itself.

• Original name from struct NAME { … } may be nested.
• Name inferred from #11 are nested. (They won’t have typedefs, except perhaps typedefs of their clones.)
• Typedef alias names are top-level because … they are.