omdev 0.0.0.dev7__py3-none-any.whl

omdev/exts/_distutils/compilers/options.py

@@ -0,0 +1,80 @@
+import os
+import typing as ta
+
+from ..util import always_iterable
+
+
+Macro: ta.TypeAlias = tuple[str, str | None] | tuple[str]
+
+
+def gen_preprocess_options(
+        macros: list[Macro],
+        include_dirs: list[str],
+) -> list[str]:
+    """
+    Generate C pre-processor options (-D, -U, -I) as used by at least two types of compilers: the typical Unix compiler
+    and Visual C++. 'macros' is the usual thing, a list of 1- or 2-tuples, where (name,) means undefine (-U) macro
+    'name', and (name,value) means define (-D) macro 'name' to 'value'.  'include_dirs' is just a list of directory
+    names to be added to the header file search path (-I).  Returns a list of command-line options suitable for either
+    Unix compilers or Visual C++.
+    """
+    # it would be nice (mainly aesthetic, and so we don't generate stupid-looking command lines) to go over 'macros' and
+    # eliminate redundant definitions/undefinitions (ie. ensure that only the latest mention of a particular macro winds
+    # up on the command line).  I don't think it's essential, though, since most (all?) Unix C compilers only pay
+    # attention to the latest -D or -U mention of a macro on their command line.  Similar situation for 'include_dirs'.
+    # I'm punting on both for now.  Anyways, weeding out redundancies like this should probably be the province of
+    # CCompiler, since the data structures used are inherited from it and therefore common to all CCompiler classes.
+    pp_opts: list[str] = []
+    for macro in macros:
+        if not (isinstance(macro, tuple) and 1 <= len(macro) <= 2):
+            raise TypeError(f"bad macro definition '{macro}': each element of 'macros' list must be a 1- or 2-tuple")
+
+        if len(macro) == 1:  # undefine this macro
+            pp_opts.append(f'-U{macro[0]}')
+        elif len(macro) == 2:
+            if macro[1] is None:  # define with no explicit value
+                pp_opts.append(f'-D{macro[0]}')
+            else:
+                # *don't* need to be clever about quoting the macro value here, because we're going to avoid the shell
+                # at all costs when we spawn the command!
+                pp_opts.append('-D{}={}'.format(*macro))
+
+    for dir in include_dirs:  # noqa
+        pp_opts.append(f'-I{dir}')
+    return pp_opts
+
+
+def gen_lib_options(
+        compiler,
+        library_dirs: list[str],
+        runtime_library_dirs: list[str],
+        libraries: list[str],
+) -> list[str]:
+    """
+    Generate linker options for searching library directories and linking with specific libraries.  'libraries' and
+    'library_dirs' are, respectively, lists of library names (not filenames!) and search directories.  Returns a list of
+    command-line options suitable for use with some compiler (depending on the two format strings passed in).
+    """
+    lib_opts = []
+
+    for dir in library_dirs:  # noqa
+        lib_opts.append(compiler.library_dir_option(dir))
+
+    for dir in runtime_library_dirs:  # noqa
+        lib_opts.extend(always_iterable(compiler.runtime_library_dir_option(dir)))
+
+    # it's important that we *not* remove redundant library mentions! sometimes you really do have to say "-lfoo -lbar
+    # -lfoo" in order to resolve all symbols.  I just hope we never have to say "-lfoo obj.o -lbar" to get things to
+    # work -- that's certainly a possibility, but a pretty nasty way to arrange your C code.
+
+    for lib in libraries:
+        (lib_dir, lib_name) = os.path.split(lib)
+        if lib_dir:
+            lib_file = compiler.find_library_file([lib_dir], lib_name)
+            if lib_file:
+                lib_opts.append(lib_file)
+            else:
+                compiler.warn(f"no library file corresponding to '{lib}' found (skipping)")
+        else:
+            lib_opts.append(compiler.library_option(lib))
+    return lib_opts

omdev/exts/_distutils/compilers/unixccompiler.py

@@ -0,0 +1,385 @@
+"""
+Contains the UnixCCompiler class, a subclass of CCompiler that handles
+the "typical" Unix-style command-line C compiler:
+  * macros defined with -Dname[=value]
+  * macros undefined with -Uname
+  * include search directories specified with -Idir
+  * libraries specified with -lllib
+  * library search directories specified with -Ldir
+  * compile handled by 'cc' (or similar) executable with -c option: compiles .c to .o
+  * link static library handled by 'ar' command (possibly with 'ranlib')
+  * link shared library handled by 'cc -shared'
+"""
+from __future__ import annotations
+
+import importlib
+import itertools
+import logging
+import os
+import re
+import shlex
+import sys
+import typing as ta
+
+from .. import sysconfig
+from ..errors import CompileError
+from ..errors import DistutilsExecError
+from ..errors import LibError
+from ..errors import LinkError
+from ..modified import newer
+from .ccompiler import CCompiler
+from .options import gen_lib_options
+from .options import gen_preprocess_options
+
+
+log = logging.getLogger(__name__)
+
+
+def bypass_compiler_fixup(cmd, args):
+    return cmd
+
+
+if sys.platform == 'darwin':
+    compiler_fixup = importlib.import_module('_osx_support').compiler_fixup
+else:
+    compiler_fixup = bypass_compiler_fixup
+
+
+# Things not currently handled:
+#   * optimization/debug/warning flags; we just use whatever's in Python's Makefile and live with it.  Is this adequate?
+#      If not, we might have to have a bunch of subclasses GNUCCompiler, SGICCompiler, SunCCompiler, and I suspect down
+#     that road lies madness.
+#   * even if we don't know a warning flag from an optimization flag, we need some way for outsiders to feed
+#     preprocessor/compiler/linker flags in to us -- eg. a sysadmin might want to mandate certain flags via a site
+#     config file, or a user might want to set something for compiling this module distribution only via the setup.py
+#     command line, whatever.  As long as these options come from something on the current system, they can be as
+#     system-dependent as they like, and we should just happily stuff them into the preprocessor/compiler/linker options
+#     and carry on.
+
+
+def _split_env(cmd: list[str]) -> tuple[list[str], list[str]]:
+    """
+    For macOS, split command into 'env' portion (if any) and the rest of the linker command.
+
+    >>> _split_env(['a', 'b', 'c'])
+    ([], ['a', 'b', 'c'])
+    >>> _split_env(['/usr/bin/env', 'A=3', 'gcc'])
+    (['/usr/bin/env', 'A=3'], ['gcc'])
+    """
+    pivot = 0
+    if os.path.basename(cmd[0]) == 'env':
+        pivot = 1
+        while '=' in cmd[pivot]:
+            pivot += 1
+    return cmd[:pivot], cmd[pivot:]
+
+
+def _split_aix(cmd: list[str]) -> tuple[list[str], list[str]]:
+    """
+    AIX platforms prefix the compiler with the ld_so_aix
+    script, so split that from the linker command.
+
+    >>> _split_aix(['a', 'b', 'c'])
+    ([], ['a', 'b', 'c'])
+    >>> _split_aix(['/bin/foo/ld_so_aix', 'gcc'])
+    (['/bin/foo/ld_so_aix'], ['gcc'])
+    """
+    pivot = os.path.basename(cmd[0]) == 'ld_so_aix'
+    return cmd[:pivot], cmd[pivot:]
+
+
+def _linker_params(linker_cmd: list[str], compiler_cmd: list[str]) -> list[str]:
+    """
+    The linker command usually begins with the compiler command (possibly multiple elements), followed by zero or more
+    params for shared library building.
+
+    If the LDSHARED env variable overrides the linker command, however, the commands may not match.
+
+    Return the best guess of the linker parameters by stripping the linker command. If the compiler command does not
+    match the linker command, assume the linker command is just the first element.
+
+    >>> _linker_params('gcc foo bar'.split(), ['gcc'])
+    ['foo', 'bar']
+    >>> _linker_params('gcc foo bar'.split(), ['other'])
+    ['foo', 'bar']
+    >>> _linker_params('ccache gcc foo bar'.split(), 'ccache gcc'.split())
+    ['foo', 'bar']
+    >>> _linker_params(['gcc'], ['gcc'])
+    []
+    """
+    c_len = len(compiler_cmd)
+    pivot = c_len if linker_cmd[:c_len] == compiler_cmd else 1
+    return linker_cmd[pivot:]
+
+
+def consolidate_linker_args(args: list[str]) -> str | list[str]:
+    """
+    Ensure the return value is a string for backward compatibility.
+
+    Retain until at least 2024-04-31. See pypa/distutils#246
+    """
+
+    if not all(arg.startswith('-Wl,') for arg in args):
+        return args
+    return '-Wl,' + ','.join(arg.removeprefix('-Wl,') for arg in args)
+
+
+class UnixCCompiler(CCompiler):
+    compiler_type = 'unix'
+
+    # These are used by CCompiler in two places: the constructor sets instance attributes 'preprocessor', 'compiler',
+    # etc. from them, and 'set_executable()' allows any of these to be set.  The defaults here are pretty generic; they
+    # will probably have to be set by an outsider (eg. using information discovered by the sysconfig about building
+    # Python extensions).
+    executables = {  # noqa
+        'preprocessor': None,
+        'compiler': ['cc'],
+        'compiler_so': ['cc'],
+        'compiler_cxx': ['cc'],
+        'linker_so': ['cc', '-shared'],
+        'linker_exe': ['cc'],
+        'archiver': ['ar', '-cr'],
+        'ranlib': None,
+    }
+
+    if sys.platform[:6] == 'darwin':
+        executables['ranlib'] = ['ranlib']
+
+    # Needed for the filename generation methods provided by the base class, CCompiler.  NB. whoever instantiates/uses a
+    # particular UnixCCompiler instance should set 'shared_lib_ext' -- we set a reasonable common default here, but it's
+    # not necessarily used on all Unices!
+
+    src_extensions: ta.ClassVar[list[str]] = ['.c', '.C', '.cc', '.cxx', '.cpp', '.m']
+    obj_extension = '.o'
+    static_lib_extension = '.a'
+    shared_lib_extension = '.so'
+    dylib_lib_extension = '.dylib'
+    xcode_stub_lib_extension = '.tbd'
+    static_lib_format = shared_lib_format = dylib_lib_format = 'lib%s%s'
+    xcode_stub_lib_format = dylib_lib_format
+
+    def preprocess(
+            self,
+            source,
+            output_file=None,
+            macros=None,
+            include_dirs=None,
+            extra_preargs=None,
+            extra_postargs=None,
+    ):
+        fixed_args = self._fix_compile_args(None, macros, include_dirs)
+        ignore, macros, include_dirs = fixed_args
+        pp_opts = gen_preprocess_options(macros, include_dirs)
+        pp_args = self.preprocessor + pp_opts
+        if output_file:
+            pp_args.extend(['-o', output_file])
+        if extra_preargs:
+            pp_args[:0] = extra_preargs
+        if extra_postargs:
+            pp_args.extend(extra_postargs)
+        pp_args.append(source)
+
+        # reasons to preprocess:
+        # - force is indicated
+        # - output is directed to stdout
+        # - source file is newer than the target
+        preprocess = self.force or output_file is None or newer(source, output_file)
+        if not preprocess:
+            return
+
+        if output_file:
+            self.mkpath(os.path.dirname(output_file))
+
+        try:
+            self.spawn(pp_args)
+        except DistutilsExecError as msg:
+            raise CompileError(msg) from None
+
+    def _compile(self, obj, src, ext, cc_args, extra_postargs, pp_opts):
+        compiler_so = compiler_fixup(self.compiler_so, cc_args + extra_postargs)
+        try:
+            self.spawn(compiler_so + cc_args + [src, '-o', obj] + extra_postargs)
+        except DistutilsExecError as msg:
+            raise CompileError(msg) from None
+
+    def create_static_lib(
+            self,
+            objects,
+            output_libname,
+            output_dir=None,
+            debug=0,
+            target_lang=None,
+    ):
+        objects, output_dir = self._fix_object_args(objects, output_dir)
+
+        output_filename = self.library_filename(output_libname, output_dir=output_dir)
+
+        if self._need_link(objects, output_filename):
+            self.mkpath(os.path.dirname(output_filename))
+            self.spawn([*self.archiver, output_filename, *objects, *self.objects])
+
+            # Not many Unices required ranlib anymore -- SunOS 4.x is, I think the only major Unix that does.  Maybe we
+            # need some platform intelligence here to skip ranlib if it's not needed -- or maybe Python's configure
+            # script took care of it for us, hence the check for leading colon.
+            if self.ranlib:
+                try:
+                    self.spawn([*self.ranlib, output_filename])
+                except DistutilsExecError as msg:
+                    raise LibError(msg) from None
+        else:
+            log.debug('skipping %s (up-to-date)', output_filename)
+
+    def link(
+            self,
+            target_desc,
+            objects,
+            output_filename,
+            output_dir=None,
+            libraries=None,
+            library_dirs=None,
+            runtime_library_dirs=None,
+            export_symbols=None,
+            debug=0,
+            extra_preargs=None,
+            extra_postargs=None,
+            build_temp=None,
+            target_lang=None,
+    ):
+        objects, output_dir = self._fix_object_args(objects, output_dir)
+        fixed_args = self._fix_lib_args(libraries, library_dirs, runtime_library_dirs)
+        libraries, library_dirs, runtime_library_dirs = fixed_args
+
+        lib_opts = gen_lib_options(self, library_dirs, runtime_library_dirs, libraries)
+        if not isinstance(output_dir, (str, type(None))):
+            raise TypeError("'output_dir' must be a string or None")
+        if output_dir is not None:
+            output_filename = os.path.join(output_dir, output_filename)
+
+        if self._need_link(objects, output_filename):
+            ld_args = objects + self.objects + lib_opts + ['-o', output_filename]
+            if debug:
+                ld_args[:0] = ['-g']
+            if extra_preargs:
+                ld_args[:0] = extra_preargs
+            if extra_postargs:
+                ld_args.extend(extra_postargs)
+            self.mkpath(os.path.dirname(output_filename))
+            try:
+                # Select a linker based on context: linker_exe when building an executable or linker_so (with shared
+                # options) when building a shared library.
+                building_exe = target_desc == CCompiler.EXECUTABLE
+                linker = (self.linker_exe if building_exe else self.linker_so)[:]
+
+                if target_lang == 'c++' and self.compiler_cxx:
+                    env, linker_ne = _split_env(linker)
+                    aix, linker_na = _split_aix(linker_ne)
+                    _, compiler_cxx_ne = _split_env(self.compiler_cxx)
+                    _, linker_exe_ne = _split_env(self.linker_exe)
+
+                    params = _linker_params(linker_na, linker_exe_ne)
+                    linker = env + aix + compiler_cxx_ne + params
+
+                linker = compiler_fixup(linker, ld_args)
+
+                self.spawn(linker + ld_args)
+            except DistutilsExecError as msg:
+                raise LinkError(msg) from None
+        else:
+            log.debug('skipping %s (up-to-date)', output_filename)
+
+    # -- Miscellaneous methods -----------------------------------------
+    # These are all used by the 'gen_lib_options() function, in ccompiler.py.
+
+    def library_dir_option(self, dir):  # noqa
+        return '-L' + dir
+
+    def _is_gcc(self):
+        cc_var = sysconfig.get_config_var('CC')
+        compiler = os.path.basename(shlex.split(cc_var)[0])
+        return 'gcc' in compiler or 'g++' in compiler
+
+    def runtime_library_dir_option(self, dir: str) -> str | list[str]:  # noqa
+        # Hackish, at the very least.  See Python bug #445902: https://bugs.python.org/issue445902 Linkers on different
+        # platforms need different options to specify that directories need to be added to the list of directories
+        # searched for dependencies when a dynamic library is sought.  GCC on GNU systems (Linux, FreeBSD, ...) has to
+        # be told to pass the -R option through to the linker, whereas other compilers and gcc on other systems just
+        # know this. Other compilers may need something slightly different.  At this time, there's no way to determine
+        # this information from the configuration data stored in the Python installation, so we use this hack.
+        if sys.platform[:6] == 'darwin':
+            from ..util import get_macosx_target_ver
+            from ..util import split_version
+
+            macosx_target_ver = get_macosx_target_ver()
+            if macosx_target_ver and split_version(macosx_target_ver) >= [10, 5]:
+                return '-Wl,-rpath,' + dir
+            else:  # no support for -rpath on earlier macOS versions
+                return '-L' + dir
+        elif sys.platform[:7] == 'freebsd':
+            return '-Wl,-rpath=' + dir
+        elif sys.platform[:5] == 'hp-ux':
+            return [
+                '-Wl,+s' if self._is_gcc() else '+s',
+                '-L' + dir,
+            ]
+
+        # For all compilers, `-Wl` is the presumed way to pass a compiler option to the linker
+        if sysconfig.get_config_var('GNULD') == 'yes':
+            return consolidate_linker_args([
+                # Force RUNPATH instead of RPATH
+                '-Wl,--enable-new-dtags',
+                '-Wl,-rpath,' + dir,
+            ])
+        else:
+            return '-Wl,-R' + dir
+
+    def library_option(self, lib):
+        return '-l' + lib
+
+    @staticmethod
+    def _library_root(dir):  # noqa
+        """
+        macOS users can specify an alternate SDK using'-isysroot'. Calculate the SDK root if it is specified.
+
+        Note that, as of Xcode 7, Apple SDKs may contain textual stub libraries with .tbd extensions rather than the
+        normal .dylib shared libraries installed in /.  The Apple compiler tool chain handles this transparently but it
+        can cause problems for programs that are being built with an SDK and searching for specific libraries.  Callers
+        of find_library_file need to keep in mind that the base filename of the returned SDK library file might have a
+        different extension from that of the library file installed on the running system, for example:
+          /Applications/Xcode.app/Contents/Developer/Platforms/
+              MacOSX.platform/Developer/SDKs/MacOSX10.11.sdk/
+              usr/lib/libedit.tbd
+        vs
+          /usr/lib/libedit.dylib
+        """
+        cflags = sysconfig.get_config_var('CFLAGS')
+        match = re.search(r'-isysroot\s*(\S+)', cflags)
+
+        apply_root = (
+            sys.platform == 'darwin'
+            and match
+            and (
+                dir.startswith('/System/')
+                or (dir.startswith('/usr/') and not dir.startswith('/usr/local/'))
+            )
+        )
+
+        return os.path.join(match.group(1), dir[1:]) if match and apply_root else dir
+
+    def find_library_file(self, dirs, lib, debug=0):
+        """
+        Second-guess the linker with not much hard data to go on: GCC seems to prefer the shared library, so assume that
+        *all* Unix C compilers do, ignoring even GCC's "-static" option.
+        """
+        lib_names = (
+            self.library_filename(lib, lib_type=ty)
+            for ty in 'dylib xcode_stub shared static'.split()
+        )
+
+        roots = map(self._library_root, dirs)
+
+        searched = itertools.starmap(os.path.join, itertools.product(roots, lib_names))
+
+        found = filter(os.path.exists, searched)
+
+        # Return None if it could not be found in any dir.
+        return next(found, None)

omdev/exts/_distutils/dir_util.py

@@ -0,0 +1,76 @@
+"""Utility functions for manipulating directories and directory trees."""
+import errno
+import logging
+import os
+
+from .errors import DistutilsFileError
+from .errors import DistutilsInternalError
+
+
+log = logging.getLogger(__name__)
+
+
+# cache for by mkpath() -- in addition to cheapening redundant calls, eliminates redundant "creating /foo/bar/baz"
+# messages in dry-run mode
+_path_created: dict[str, int] = {}
+
+
+def mkpath(name, mode=0o777, verbose=1, dry_run=False) -> list[str]:  # noqa: C901
+    """Create a directory and any missing ancestor directories.
+
+    If the directory already exists (or if 'name' is the empty string, which means the current directory, which of
+    course exists), then do nothing. Raise DistutilsFileError if unable to create some directory along the way (eg. some
+    sub-path exists, but is a file rather than a directory). If 'verbose' is true, print a one-line summary of each
+    mkdir to stdout. Return the list of directories actually created.
+
+    os.makedirs is not used because:
+
+    a) It's new to Python 1.5.2, and
+    b) it blows up if the directory already exists (in which case it should silently succeed).
+    """
+
+    # Detect a common bug -- name is None
+    if not isinstance(name, str):
+        raise DistutilsInternalError(f"mkpath: 'name' must be a string (got {name!r})")
+
+    # what's the better way to handle verbosity? print as we create each directory in the path (the current behaviour),
+    # or only announce the creation of the whole path? (quite easy to do the latter since we're not using a recursive
+    # algorithm)
+
+    name = os.path.normpath(name)
+    created_dirs: list[str] = []
+    if os.path.isdir(name) or name == '':
+        return created_dirs
+    if _path_created.get(os.path.abspath(name)):
+        return created_dirs
+
+    (head, tail) = os.path.split(name)
+    tails = [tail]  # stack of lone dirs to create
+
+    while head and tail and not os.path.isdir(head):
+        (head, tail) = os.path.split(head)
+        tails.insert(0, tail)  # push next higher dir onto stack
+
+    # now 'head' contains the deepest directory that already exists (that is, the child of 'head' in 'name' is the
+    # highest directory that does *not* exist)
+    for d in tails:
+        # print "head = %s, d = %s: " % (head, d),
+        head = os.path.join(head, d)
+        abs_head = os.path.abspath(head)
+
+        if _path_created.get(abs_head):
+            continue
+
+        if verbose >= 1:
+            log.info('creating %s', head)
+
+        if not dry_run:
+            try:
+                os.mkdir(head, mode)
+            except OSError as exc:
+                if not (exc.errno == errno.EEXIST and os.path.isdir(head)):
+                    raise DistutilsFileError(f"could not create '{head}': {exc.args[-1]}") from None
+            created_dirs.append(head)
+
+        _path_created[abs_head] = 1
+    return created_dirs

omdev/exts/_distutils/errors.py

@@ -0,0 +1,62 @@
+"""
+Provides exceptions used by the Distutils modules.  Note that Distutils modules may raise standard exceptions; in
+particular, SystemExit is usually raised for errors that are obviously the end-user's fault (eg. bad command-line
+arguments).
+
+This module is safe to use in "from ... import *" mode; it only exports symbols whose names start with "Distutils" and
+end with "Error".
+"""
+
+
+class DistutilsError(Exception):
+    """The root of all Distutils evil."""
+
+
+class DistutilsModuleError(DistutilsError):
+    """
+    Unable to load an expected module, or to find an expected class within some module (in particular, command modules
+    and classes).
+    """
+
+
+class DistutilsFileError(DistutilsError):
+    """
+    Any problems in the filesystem: expected file not found, etc. Typically this is for problems that we detect before
+    OSError could be raised.
+    """
+
+
+class DistutilsPlatformError(DistutilsError):
+    """
+    We don't know how to do something on the current platform (but we do know how to do it on some platform) -- eg.
+    trying to compile C files on a platform not supported by a CCompiler subclass.
+    """
+
+
+class DistutilsExecError(DistutilsError):
+    """Any problems executing an external program (such as the C compiler, when compiling C files)."""
+
+
+class DistutilsInternalError(DistutilsError):
+    """Internal inconsistencies or impossibilities (obviously, this should never be seen if the code is working!)."""
+
+
+# Exception classes used by the CCompiler implementation classes
+class CCompilerError(Exception):
+    """Some compile/link operation failed."""
+
+
+class CompileError(CCompilerError):
+    """Failure to compile one or more C/C++ source files."""
+
+
+class LibError(CCompilerError):
+    """Failure to create a static library from one or more C/C++ object files."""
+
+
+class LinkError(CCompilerError):
+    """Failure to link one or more C/C++ object files into an executable or shared library file."""
+
+
+class UnknownFileError(CCompilerError):
+    """Attempt to process an unknown file type."""