解决Python-C-API安装报错：无法解析PyInit_gimli符号

你尝试将C语言实现的Gimli哈希算法封装为Python扩展库，执行pip install .时触发链接错误，提示无法解析PyInit_gimli，导致安装失败。完整报错信息如下：

$ pip install .
Processing c:\users\angga danar\documents\skripsi\project\gimli
  Preparing metadata (setup.py) ... done
Installing collected packages: gimlihash
  DEPRECATION: gimlihash is being installed using the legacy 'setup.py install' method, because it does not have a 'pyproject.toml' and the 'wheel' package is not installed. pip 23.1 will enforce this behaviour change. A possible replacement is to enable the '--use-pep517' option. Discussion can be found at https://github.com/pypa/pip/issues/8559
  Running setup.py install for gimlihash ... error
  error: subprocess-exited-with-error
  
  × Running setup.py install for gimlihash did not run successfully.
  │ exit code: 1
  ╰─> [17 lines of output]
      running install
      C:\python3.10\lib\site-packages\setuptools\command\install.py:34: SetuptoolsDeprecationWarning: setup.py install is deprecated. Use build and pip and other standards-based tools.
        warnings.warn(
      running build
      running build_ext
      building 'gimli' extension
      creating build
      creating build\temp.win-amd64-cpython-310
      creating build\temp.win-amd64-cpython-310\Release
      creating build\temp.win-amd64-cpython-310\Release\Hash
      "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.34.31933\bin\HostX86\x64\cl.exe" /c /nologo /O2 /W3 /GL /DNDEBUG /MD -IC:\python3.10\include -IC:\python3.10\Include "-IC:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.34.31933\include" "-IC:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.34.31933\ATLMFC\include" "-IC:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\VS\include" "-IC:\Program Files (x86)\Windows Kits\10\include\10.0.22621.0\ucrt" "-IC:\Program Files (x86)\Windows Kits\10\\include\10.0.22621.0\\um" "-IC:\Program Files (x86)\Windows Kits\10\\include\10.0.22621.0\\shared" "-IC:\Program Files (x86)\Windows Kits\10\\include\10.0.22621.0\\winrt" "-IC:\Program Files (x86)\Windows Kits\10\\include\10.0.22621.0\\cppwinrt" "-IC:\Program Files (x86)\Windows Kits\NETFXSDK\4.8\include\um" /TcHash/hashing.c /Fobuild\temp.win-amd64-cpython-310\Release\Hash/hashing.obj
      hashing.c
      creating C:\Users\Angga Danar\Documents\skripsi\Project\Gimli\build\lib.win-amd64-cpython-310
      "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.34.31933\bin\HostX86\x64\link.exe" /nologo /INCREMENTAL:NO /LTCG /DLL /MANIFEST:EMBED,ID=2 /MANIFESTUAC:NO /LIBPATH:C:\python3.10\libs /LIBPATH:C:\python3.10 /LIBPATH:C:\python3.10\PCbuild\amd64 "/LIBPATH:C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.34.31933\ATLMFC\lib\x64" "/LIBPATH:C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.34.31933\lib\x64" "/LIBPATH:C:\Program Files (x86)\Windows Kits\NETFXSDK\4.8\lib\um\x64" "/LIBPATH:C:\Program Files (x86)\Windows Kits\10\lib\10.0.22621.0\ucrt\x64" "/LIBPATH:C:\Program Files (x86)\Windows Kits\10\\lib\10.0.22621.0\\um\x64" /EXPORT:PyInit_gimli build\temp.win-amd64-cpython-310\Release\Hash/hashing.obj /OUT:build\lib.win-amd64-cpython-310\gimli.cp310-win_amd64.pyd /IMPLIB:build\temp.win-amd64-cpython-310\Release\Hash\gimli.cp310-win_amd64.lib
      LINK : error LNK2001: unresolved external symbol PyInit_gimli
      build\temp.win-amd64-cpython-310\Release\Hash\gimli.cp310-win_amd64.lib : fatal error LNK1120: 1 unresolved externals
      error: command 'C:\\Program Files (x86)\\Microsoft Visual Studio\\2022\\BuildTools\\VC\\Tools\\MSVC\\14.34.31933\\bin\\HostX86\\x64\\link.exe' failed with exit code 1120
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
error: legacy-install-failure

× Encountered error while trying to install package.
╰─> gimlihash

note: This is an issue with the package mentioned above, not pip.
hint: See above for output from the failure.

错误原因分析 #

链接错误的核心问题是Python扩展模块的初始化函数名与setup.py中定义的模块名不匹配：

• 在setup.py中，你定义的扩展模块名为gimli（Extension("gimli", ...)）
• 根据Python C API规范，模块初始化函数必须命名为PyInit_<模块名>，即此处需要PyInit_gimli，但你的C代码里写的是PyInit_hash，导致链接器找不到对应符号。

此外，你的C代码还存在其他逻辑错误，会导致后续运行失败，需一并修复。

修复步骤 #

1. 修改C代码的模块初始化函数与逻辑 #

将初始化函数名改为PyInit_gimli，同步修正模块定义名称，并修复字符串处理、循环逻辑等问题：

#include <Python.h>
#include <string.h>
#include <stdio.h>
#include <stdint.h>

// 补充Gimli哈希的具体实现（或引入对应头文件）
void Gimli_hash(const uint8_t *input, size_t input_len, uint8_t *output, size_t output_len) {
    // 此处添加Gimli哈希算法的实现代码
}

int print_tex(const char* string, char* hex_string) {
    uint8_t output[32];
    size_t input_len = strlen(string);
    Gimli_hash((const uint8_t*)string, input_len, output, 32);
    
    // 将哈希值转为十六进制字符串（32字节对应64个字符+终止符）
    for (int i = 0; i < 32; ++i) {
        sprintf(&hex_string[i*2], "%02x", output[i]);
    }
    hex_string[64] = '\0'; // 添加字符串终止符
    return 0;
}

static PyObject* gimli_hash(PyObject *self, PyObject *args) {
    char *str;
    char hex_result[65]; // 存储64个十六进制字符+终止符
    
    if (!PyArg_ParseTuple(args, "s", &str)) {
        return NULL;
    }
    
    print_tex(str, hex_result);
    return PyUnicode_FromString(hex_result);
}

static PyMethodDef GimliMethods[] = {
    {"hash", gimli_hash, METH_VARARGS, "计算输入字符串的Gimli哈希值"},
    {NULL, NULL, 0, NULL}
};

static struct PyModuleDef gimliModule = {
    PyModuleDef_HEAD_INIT,
    "gimli", // 模块名必须与setup.py中的定义一致
    "Gimli哈希算法Python扩展模块",
    -1,
    GimliMethods
};

PyMODINIT_FUNC PyInit_gimli(void) { // 函数名必须为PyInit_<模块名>
    return PyModule_Create(&gimliModule);
}

2. 确认setup.py配置正确 #

你的setup.py模块名配置本身正确，无需修改，若想避免deprecation警告，可添加pyproject.toml文件：

from setuptools import setup, Extension

setup(
    name="gimlihash",
    version="0.1",
    ext_modules=[Extension("gimli", ["Hash/hashing.c"])]
)

额外注意事项 #

• 必须包含Gimli哈希实现：原始代码中调用了Gimli_hash但未实现或引入头文件，编译时会出现未定义符号错误，需补充该函数的具体实现。
• 字符串处理修正：直接将uint8_t哈希值转为char数组会包含不可打印字符，改为十六进制字符串更符合Python使用习惯。
• 循环逻辑修复：原始print_tex函数中hex_string[i] = (char)output[i];不在for循环大括号内，属于逻辑错误，已修正。

内容的提问来源于stack exchange，提问作者Angga Danar Prasetyo