Qt common library

================================================

Author：Kang Lin（[email protected])

🇨🇳 Chinese

• Project home site: https://github.com/KangLin/RabbitCommon
• Mirror:
  • https://sourceforge.net/projects/rabbitcommon/
  • https://launchpad.net/rabbitcommon
  • https://gitlab.com/kl222/RabbitCommon
  • https://invent.kde.org/kanglin/RabbitCommon
  • https://gitee.com/kl222/RabbitCommon
  • https://bitbucket.org/kl222/rabbitcommon

Developer documents

Online developer documents

Latest release

• Latest release
• See:
  • Semantic Versioning: https://semver.org/

Functions

API

Qt common library. include follow functions:

• GUI

  • About
    • cmark: support MarkDown
  • Updater
  • Style (include icon theme)
  • Recent open menu
  • Title bar
  • Folder browser

• Download the same file from multiple URLs

• Directory functions

• Encrypt

• Register

• Tools

  • Execute the program with administrator privileges
  • The program starts automatically
  • Directory functions
  • Get system information
    • Get current login user name

• cmake functions

  • Translations
  • Add target, plugin target
  • Generate pkg-config configure file
  • Generate cmake configure file
  • Add uninstall target

• Cross-platform, support multiple operating systems

  • Windows
  • Linux、Unix
  • Android
  • Mac os
  • IOS

  Mac os and IOS, I don't have the corresponding equipment, please compile and test the students with the corresponding equipment.

  See: Qt5, Qt6

Compile

• Create and entry build directory

    git clone --recursive https://github.com/KangLin/RabbitCommon.git
    cd RabbitCommon
    mkdir build
  

• Compile

  • Use cmake

    cd build
    cmake ..  -DCMAKE_BUILD_TYPE=Release
        -DQT_DIR=... \
        -DQt5_DIR=${QT_ROOT}/lib/cmake/Qt5
    cmake --build .
    

    • Parameter
      • CMAKE_BUILD_TYPE: build type(MUST)
      • QT_DIR: Qt install position
      • BUILD_DOCS: build doxygen documents
      • BUILD_APP: build app
      • BUILD_ABOUT: build about
      • BUILD_UPDATE: build updater
      • BUILD_ADMINAUTHORISER: build admin authoriser

    NOTE: If you use MSVC, you need to add -DCMAKE_BUILD_TYPE=Debug, otherwise the following error will occur when compiling Debug:

      RabbitCommonTools.obj : error LNK2019: An external symbol that cannot be resolved "int __cdecl qInitResources_translations_RabbitCommon(void)" (?qInitResources_translations_RabbitCommon@@YAHXZ)，该符号在函数 "void __cdecl g_RabbitCommon_InitResource(void)" (?g_RabbitCommon_InitResource@@YAXXZ) 中被引用
      RabbitCommonTools.obj : error LNK2019: An external symbol that cannot be resolved "int __cdecl qCleanupResources_translations_RabbitCommon(void)" (?qCleanupResources_translations_RabbitCommon@@YAHXZ)，该符号在函数 "void __cdecl g_RabbitCommon_CleanResource(void)" (?g_RabbitCommon_CleanResource@@YAXXZ) 中被引用
    

    • linux

      cd build
      cmake .. -DCMAKE_INSTALL_PREFIX=`pwd`/install \
           -DCMAKE_BUILD_TYPE=Release \
           -DQT_DIR=... \
           -DQt5_DIR=${QT_ROOT}/lib/cmake/Qt5
      cmake --build . --config Release --target install
      

    • windows

      cd build
      cmake .. -DCMAKE_INSTALL_PREFIX=`pwd`/install ^
             -DCMAKE_BUILD_TYPE=Release ^
             -DQT_DIR=... ^
             -DQt5_DIR=${QT_ROOT}/lib/cmake/Qt5
      cmake --build . --config Release --target install
      

    • Android

      • Qt6 or laster

        cd build
        ${Qt6_DIR}/bin/qt-cmake .. -DCMAKE_BUILD_TYPE=Release
        cmake --build . --config Release
        

        Or:

        cmake .. -DCMAKE_BUILD_TYPE=Release \
            -DCMAKE_INSTALL_PREFIX=`pwd`/android-build \
            -DCMAKE_TOOLCHAIN_FILE=$Qt6_DIR/lib/cmake/Qt6/qt.toolchain.cmake
        cmake --build . --config Release
        

      • The host is linux

        cd build
        cmake .. -DCMAKE_BUILD_TYPE=Release \
               -DCMAKE_INSTALL_PREFIX=`pwd`/android-build \
               -DCMAKE_TOOLCHAIN_FILE=${ANDROID_NDK}/build/cmake/android.toolchain.cmake \
               -DANDROID_ABI="armeabi-v7a with NEON" \
               -DANDROID_PLATFORM=android-18 \
               -DQT_DIR=... \
               -DQt5_DIR=${QT_ROOT}/lib/cmake/Qt5
        cmake --build . --config Release --target all
        

      • The host is windows

        cd build
        cmake .. -G"Unix Makefiles" ^
             -DCMAKE_BUILD_TYPE=Release ^
             -DCMAKE_INSTALL_PREFIX=`pwd`/android-build ^
             -DCMAKE_TOOLCHAIN_FILE=${ANDROID_NDK}/build/cmake/android.toolchain.cmake ^
             -DCMAKE_MAKE_PROGRAM=${ANDROID_NDK}/prebuilt/windows-x86_64/bin/make.exe ^
             -DANDROID_PLATFORM=android-18 ^
             -DANDROID_ABI=arm64-v8a ^
             -DANDROID_ARM_NEON=ON ^
             -DQT_DIR=... \
             -DQt5_DIR=${QT_ROOT}/lib/cmake/Qt5
        cmake --build . --config Release --target all
        

      • Parameter Description: https://developer.android.google.cn/ndk/guides/cmake

        • ANDROID_ABI: The following values can be taken: Goal ABI. If the target ABI is not specified, CMake uses armeabi-v7a by default. Valid ABI are:
          • armeabi：CPU with software floating point arithmetic based on ARMv5TE
          • armeabi-v7a：ARMv7-based device with hardware FPU instructions (VFP v3 D16)
          • armeabi-v7a with NEON：Same as armeabi-v7a, but with NEON floating point instructions enabled. This is equivalent to setting -DANDROID_ABI=armeabi-v7a and -DANDROID_ARM_NEON=ON.
          • arm64-v8a：ARMv8 AArch64 Instruction Set
          • x86：IA-32 Instruction Set
          • x86_64 - x86-64 Instruction Set
        • ANDROID_NDK The path of installed ndk in host
        • ANDROID_PLATFORM: For a full list of platform names and corresponding Android system images, see the [Android NDK Native API] (https://developer.android.google.com/ndk/guides/stable_apis.html)
        • ANDROID_ARM_MODE
        • ANDROID_ARM_NEON
        • ANDROID_STL: Specifies the STL that CMake should use.
          • c++_shared: The shared library variant of libc++.
          • c++_static: The static library variant of libc++.
          • none: No C++ standard library support.
          • system: The system STL

      • Install apk to devices

         adb install android-build-debug.apk 
        

      • Qt6 and later

        cd build ${Qt6_DIR}/bin/qt-cmake .. -DCMAKE_BUILD_TYPE=Release cmake --build . --config Release

        Or:

        cmake .. -DCMAKE_BUILD_TYPE=Release
        -DCMAKE_INSTALL_PREFIX=pwd/android-build
        -DCMAKE_TOOLCHAIN_FILE=$Qt6_DIR/lib/cmake/Qt6/qt.toolchain.cmake cmake --build . --config Release

  • Use qmake. (Deprecated, please use CMake for new programs)

    cd build
    qmake ../RabbitCommon.pro
    make install
    

    • Parameter
      • BUILD_DOCS: build doxygen documents
      • BUILD_ABOUT=OFF: Off build about
      • BUILD_UPDATE=OFF: Off build updater
      • BUILD_ADMINAUTHORISER＝OFF: Off admin authoriser

• Compilation notes: Use Qtcreate compile for android in windows

  • qmake. It may appear that the dependent library could not be found. (Deprecated, please use CMake for new programs)

    Don't find D:\Source\build-RabbitCommon-Android_for_armeabi_v7a_Clang_Qt_5_12_4_for_Android_ARMv7-Debug\bin\libRabbitCommon.so move libRabbitCommon.so ..\bin\libRabbitCommon.so process_begin: CreateProcess(NULL, move libRabbitCommon.so ..\bin\libRabbitCommon.so, ...) failed. make (e=2): The system can not find the file specified。 make[1]: [..\bin\libRabbitCommon.so] Error 2 (ignored)

  The reason is that the make program under windows cannot convert the \ in the path. Solution: Use a make program that recognizes the \ in the path, for example: mingw32-make.exe.

  • cmake

    • Set Generator to "Unix Makefiles"
    • Set CMAKE_MAKE_PROGRAM to ${ANDROID_NDK}/prebuilt/windows-x86_64/bin/make.exe

• Install notes:

  • windows
    If you build app. Qt does not provide openssl dynamic library for copyright reasons, so you must copy the dynamic library of openssl to the installation directory.

    • If it is 32, you can find the dynamic library of openssl (libeay32.dll, ssleay32.dll) in the Qt installer Tools\QtCreator\bin directory.
    • If it is 64-bit, you will need to download the binary installation package for openssl yourself.

  • linux

  sudo apt-get install libssl1.1
  

Other application use the project

if(NOT RabbitCommon_ROOT)
    set(RabbitCommon_ROOT $ENV{RabbitCommon_ROOT})
    if(NOT RabbitCommon_ROOT)
        set(RabbitCommon_ROOT ${CMAKE_SOURCE_DIR}/../RabbitCommon)
    endif()
endif()
if(RabbitCommon_ROOT AND EXISTS ${RabbitCommon_ROOT}/Src)
    message("Use RabbitCommon source code")
    add_subdirectory(${RabbitCommon_ROOT}/Src ${CMAKE_BINARY_DIR}/RabbitCommon)
else()
    find_package(RabbitCommon)
    if(NOT RabbitCommon_FOUND)
        message("RabbitCommon_ROOT is not found. Please use one of the following ways to set it:")
        message("1. Set RabbitCommon_ROOT to the install prefix of RabbitCommon.")
        message("2. Set RabbitCommon_ROOT to source code root of RabbitCommon.")
        message("2.1 Please download the source code of RabbitCommon from https://github.com/KangLin/RabbitCommon")
        message("   ag:")
        message("       git clone https://github.com/KangLin/RabbitCommon.git ${CMAKE_SOURCE_DIR}/..")
        message("2.2 Then set cmake variable or environment variable RabbitCommon_ROOT to download root directory.")
        message("   ag:")
        message("       cmake -DRabbitCommon_ROOT=${CMAKE_SOURCE_DIR}/.. ")
        message(FATAL_ERROR "RabbitCommon_ROOT isn't set.")
    endif()
endif()

• Use in library mode

  • cmake

    Set RabbitCommon_ROOT to specify the root directory of the installed RabbitCommon

    find_package(RabbitCommon)
    

• Use the source code directly

  • cmake

    • Submodule

      add_subdirectory(3th_libs/RabbitCommon/Src)
      

    • No submodule

      • Download RabbitCommon to the same directory of the application

        git clone https://github.com/KangLin/RabbitCommon.git
        

      • Introduced to add_subdirectory this directory

          if(NOT RabbitCommon_ROOT)
              set(RabbitCommon_ROOT $ENV{RabbitCommon_ROOT})
              if(NOT RabbitCommon_ROOT)
                  set(RabbitCommon_ROOT ${CMAKE_SOURCE_DIR}/../RabbitCommon)
              endif()
          endif()
          if(RabbitCommon_ROOT AND EXISTS ${RabbitCommon_ROOT}/Src)
              message("Use RabbitCommon source code")
              add_subdirectory(${RabbitCommon_ROOT}/Src ${CMAKE_BINARY_DIR}/RabbitCommon)
          else()
              find_package(RabbitCommon)
              if(NOT RabbitCommon_FOUND)
                  message("RabbitCommon_ROOT is not found. Please use one of the following ways to set it:")
                  message("1. Set RabbitCommon_ROOT to the install prefix of RabbitCommon.")
                  message("2. Set RabbitCommon_ROOT to source code root of RabbitCommon.")
                  message("2.1 Please download the source code of RabbitCommon from https://github.com/KangLin/RabbitCommon")
                  message("   ag:")
                  message("       git clone https://github.com/KangLin/RabbitCommon.git ${CMAKE_SOURCE_DIR}/..")
                  message("2.2 Then set cmake variable or environment variable RabbitCommon_ROOT to download root directory.")
                  message("   ag:")
                  message("       cmake -DRabbitCommon_ROOT=${CMAKE_SOURCE_DIR}/.. ")
                  message(FATAL_ERROR "RabbitCommon_ROOT isn't set.")
              endif()
          endif()
        

      • Add the following code to the CMakeLists.txt file of the project

          target_link_libraries(${PROJECT_NAME} RabbitCommon)
        

    • Static library

      target_compile_definitions(${PROJECT_NAME} PRIVATE RABBITCOMMON_STATIC_DEFINE)
      

• Initialization functions is called at the beginning of main() of the program and after QApplication

    int main(int argc, char* argv[])
    {
        QApplication a(argc, argv);
        a.setApplicationName(......);
        // Because it depend on QApplication::applicationName()
        RabbitCommon::CTools::Instance()->Init();
        
        ......
    }
  

Functions

Online developer documents

About

• Install Authors、 License、 ChangeLog files.
  File name naming rules:
  Authors.md、License.md、ChangeLog.md is the default file.
  The local file naming rule is to add the local name after the default file name.
  For example: Chinese file:
  Authors_zh_CN.md、License_zh_CN.md、ChangeLog_zh_CN.md

    SET(OTHER_FILES
        ${CMAKE_SOURCE_DIR}/License.md
        ${CMAKE_SOURCE_DIR}/Authors.md
        ${CMAKE_SOURCE_DIR}/Authors_zh_CN.md
        ${CMAKE_SOURCE_DIR}/ChangeLog.md
        )
    INSTALL_FILE(SOURCES ${OTHER_FILES} DESTINATION "." COMPONENT Runtime)
  

• Used in code

   QApplication a(argc, argv);
   a.setApplicationVersion(RabbitCommon_VERSION);
   a.setApplicationName("SerialPortAssistant");
   a.setApplicationDisplayName(QObject::tr("SerialPortAssistant"));
  
   #ifdef RABBITCOMMON
       CDlgAbout about(this);
       about.m_AppIcon = QImage(":/icon/SerialPortAssistant");
       about.m_szHomePage = "https://github.com/KangLin/SerialPortAssistant";
       #if defined (Q_OS_ANDROID)
           about.showMaximized();
           about.exec();
       #else
           about.exec();
       #endif
   #endif
  

• See: https://github.com/KangLin/SerialPortAssistant

Updater

See: FrmUpdater.h

#ifdef RABBITCOMMON
    CFrmUpdater *fu = new CFrmUpdater();
    fu->SetTitle(QImage(":/image/SerialPortAssistant"), qApp->applicationDisplayName());
    #if defined (Q_OS_ANDROID)
        fu->showMaximized();
    #else
        fu->show();
    #endif
#endif

• Use CFrmUpdater::GenerateUpdateXml() to generate update xml file, use --help look up parameter

  ./TasksApp --help
  Usage: ./TasksApp [options]
  
  Options:
      -h, --help                       Displays this help.
      -v, --version                    Displays version information.
      -f, --file <xml file name>       xml file name
      --pv <Package version>           Package version
      -t, --time <Time>                Time
      -i, --info <Information>         Information
      -s, --system <Operating system>  Operating system
      -p, --platform <Platform>        Platform
      -a, --arch <Architecture>        Architecture
      -c, --md5 <MD5 checksum>         MD5 checksum
      -u, --url <Download url>         Package download url
      --home <Project home url>        Project home url
      -m, --min <Min update version>   Min update version
  

• Add Update/update.xml in project source root directory, then add the url to CFrmUpdater::DownloadFile.

  <?xml version="1.0" encoding="UTF-8"?>
      <REDIRECT>
          <VERSION>v2.3.2</VERSION>
          <WINDOWS>
              <URL>url</URL>
          </WINDOWS>
          <LINUX>
              <URL>url</URL>
          </LINUX>
          <LINUX_APPIMAGE>
              <URL>url</URL>
          </LINUX_APPIMAGE>
          <ANDROID>
              <URL>url</URL>
          </ANDROID>   
  </REDIRECT>
  

• See: https://github.com/KangLin/SerialPortAssistant

Execute the program with administrator privileges

adminauthoriser.h

• Internal implementation

  QString szCmd = "mkdir";
  QStringList paras;
  paras << "-p" << "/opt/RabbitCommonAdminAuthoriseTest";
  qDebug() << "RabbitCommon::AdminAuthoriser::Instance()->execute(szCmd, paras):"
           << RabbitCommon::AdminAuthoriser::Instance()->execute(szCmd, paras);
  

• Public interface:

  RabbitCommon::CTools::executeByRoot("regedit", QStringList());
  

The program starts automatically

The program starts automatically

  static int InstallStartRun(const QString &szName = QString(),
                           const QString &szPath = QString(),
                           bool bAllUser = false);
  static int RemoveStartRun(const QString &szName = QString(),
                       bool bAllUser = false);
  static bool IsStartRun(const QString &szName = QString(),
                       bool bAllUser = false);

Get system information

• Get current login user name:

  RabbitCommon::CTools::GetCurrentUser();
  

• Get host name:

  RabbitCommon::CTools::GetHostName();
  

Other projects using this project

• Rabbit remote control
• Rabbit IM
• Calendar
• LunarCalendar
• SerialPortAssistant
• FaceRecognizer
• TransformCoordinate
• Chinese chess control

Donation

License

License