跳转至内容

MINC/教程/CVSandPackaging

Add links
来自维基教科书，开放世界开放书籍
< MINC | 教程
此页面可能需要审查以确保质量。

这是一个关于创建 BIC 包和一些发布它的指南

包命名规则

[编辑 | 编辑源代码]

您需要做的第一件事是决定您要为您的包命名什么。一般来说，“minc”前缀保留给适用于任何 MINC 文件（mincmath、mincresample 等）的包/程序，无论是 3D、10D 还是 1D。如果您的程序/包更适合处理体积（3D），那么建议使用“vol”作为前缀。当然，过去这条规则并不总是被遵守（minctracc、mincmorph），但我们不必让它拖累我们。

您的包名称也不应该包含大写字母或下划线“_”，因为这会导致您稍后为某些系统（例如 Debian Linux）构建二进制包时出现问题。包名中允许使用数字和连字符“-”。同样，这条规则也不总是被遵守（例如 mni_autoreg），并导致了后续的痛苦。

一些好名字的例子包括

  mincshazam - the name we shall use in the examples on this page
  volpls-fmri - a package to analyse fmri data via PLS
  mincinvert - a package/program to invert a file
  voldegibbs - a package to remove gibbs ringing from an image

不要这样做

  mincprocess - far too general
  vol-do-emma-processing - processing for emma, to generic and emma will leave eventually
  vol-do-something-with-a-really-long-name
  mincfoo
  mincb

按照 BIC 方式设置 CVS

[编辑 | 编辑源代码]

到目前为止，您可能已经编写了一些代码，并将它们存储在您的主目录中，这很好，因为它是备份的，但是如果您想知道您在 3 天前做了哪些更改，您将需要使用像 CVS 这样的工具来跟踪更改。CVS 允许您通过代码库来做到这一点。本 HOWTO 假设您从现在开始使用 CVS 来管理您的代码，并且知道如何使用它。如果不是，建议您去阅读以下内容：[1]

BIC 目前的 CVSROOT 在 cvs.bic.mni.mcgill.ca 上，位于 /private-cvsroot，因此您在 .bashrc 中添加以下行将很有帮助

 $ export CVSROOT=cvs.bic.mni.mcgill.ca:/private-cvsroot
 $ export CVS_RSH=ssh

在您的情况下，第二行可能不需要，因为您将是 BIC 的本地用户，但如果您希望使用远程库，那么它将非常方便。

您可能还想通过 ~/.cshrc 文件为 CVS 命令定义一些默认值，以下是我使用的，也推荐您使用

  $ cat ~/.cvsrc
  checkout -P
  update -d -P
  diff -u -b -B
  tag -c
  
  # if you'd like cvs to be a bit quieter, comment out this
  # cvs -q

使用 man 命令了解这些命令的功能，但它们是 CVS 新用户的一套很好的默认设置

从头开始创建包

[编辑 | 编辑源代码]

虽然看起来可能会有很多开销，但我们使用 automake 和 autoconf 来打包源代码，以便我们可以确保它们可以在多种平台上编译。要开始使用它，请为自己创建一个本地 cvs 目录

  $ mkdir ~/cvs
  $ cd ~/cvs

然后导出 BIC 示例包的副本

  $ cvs export -r HEAD libraries/mni-example-package

然后决定您要将您的包放在 cvs 的哪里（查看 /software/source）。; 如果您需要有关放置包位置的帮助，请发送电子邮件给 Andrew Janke：[email protected]。现在，我们假设我们要将我们的包放在 libraries 中。重命名示例包

  $ mv libraries/mni-example-package libraries/mincshazam
  $ cd libraries/mincshazam

在 AUTHORS 文件中放置包创建者的姓名和电子邮件地址

  $ cat AUTHORS 
  Andrew Janke <[email protected]>

将您要使用的许可证添加到 COPYING 文件中。在本例中，我们使用了 MINC 修改的 BSD 样式许可证。有关使用哪种许可证的指南/建议，请参见下面的“许可证”。

  $ cat COPYING 
  Copyright 2006-2007 Andrew L Janke
  McConnell Brain Imaging Centre
  Montreal Neurological Institute
  McGill University
  
  Permission to use, copy, modify, and distribute this software and its
  documentation for any purpose and without fee is hereby granted,
  provided that the above copyright notice appear in all copies.  The
  author and McGill University make no representations about the
  suitability of this software for any purpose.  It is provided "as is"
  without express or implied warranty.

编写 README 文件。您在当前目录中已经存在的 README 文件应该被阅读和消化。它比本 HOWTO 更详细地描述了您可以在哪里获取有关 automake、autoconf 和相关工具的更多信息。请记住，README 是包构建者将（或至少应该）阅读的第一个文件。

  $ cat README
  The mincshazam package contains mincshazam
  
  It does magic on minc files so amazing that all people should have it.
  If you don't like it, too bad.

复制您的源文件，并删除示例。

  $ cp ~/src/good_stuff/mincshazam.c .
  $ rm -f example_tags.c example_volume_io.c example_modify.c

编辑 configure.ac 以适应（阅读 autoconf 手册页和类似内容以获取更多信息）。总而言之，只需编辑给出的示例就可以满足大多数目的。最重要的部分是填写 AC_INIT 的三个组成部分。稍后，当我们构建一个完整的 BIC 包时，这是通过 -version 标志返回给您的程序的信息。

  $ cat configure.ac 
  # Require autoconf 2.57 or newer.
  AC_PREREQ([2.57])
  
  # The arguments are package name, and package version.
  AC_INIT([mincshazam],[1.0], [Andrew Janke <[email protected]>])
  
  # The argument is any source file distributed with the package.
  AC_CONFIG_SRCDIR([mincshazam.c])
  
  AM_INIT_AUTOMAKE
  
  # The argument is the name of the generated header file.
  # It is recommended to leave it as "config.h".
  AC_CONFIG_HEADERS([config.h])
  
  # This macro eases building the package; see m4/README.
  smr_WITH_BUILD_PATH
  
  # Checks for programs.
  AC_PROG_CC
  AC_PROG_INSTALL
  
  # Checks for libraries.  See m4/README.
  mni_REQUIRE_VOLUMEIO
  
  # Finish up by writing output files.
  AC_CONFIG_FILES([Makefile])
  AC_OUTPUT

将您的源文件添加到 Makefile.am 中。同样，请参阅 automake 文档以获取有关此文件的更多信息。和所有与 Make 相关的事情一样，在缩进时请确保使用制表符而不是空格。我怀疑 automake 在某些版本中可能可以处理空格，但您永远不知道，最好谨慎行事。

  $ cat Makefile.am 
  AUTOMAKE_OPTIONS = check-news
  ACLOCAL_AMFLAGS = -I m4
  
  bin_PROGRAMS = mincshazam
  
  EXTRA_DIST = $(m4_files)
  
  m4_files = m4/mni_REQUIRE_LIB.m4 m4/mni_REQUIRE_MNILIBS.m4       \
          m4/mni_REQUIRE_OPENINVENTOR.m4                           \
          m4/mni_cxx_have_koenig_lookup.m4 m4/smr_CGAL_MAKEFILE.m4 \
          m4/smr_OPTIONAL_LIB.m4 m4/smr_REQUIRED_LIB.m4            \
          m4/smr_WITH_BUILD_PATH.m4
  
  mincshazam_SOURCES = mincshazam.c

在 ChangeLog 中编写您的条目。ChangeLog 的目的是以简单（易懂）的方式向其他开发者传达您对存储库所做的更改摘要，这些更改作为 CVS 提交的一部分。它不必像您在 CVS 提交中输入的信息那样详细，而应该包含更改的一般原因的摘要。

  $ cat ChangeLog 
  2006-04-06  Andrew L. Janke  <[email protected]>
  
       * made this marvelous package
       * Added the -version option

创建一个空的 NEWS 文件。当我们稍后进行第一次发布时，这个文件将派上用场。

  echo  > NEWS

您不应该修改 autogen.sh 中的任何内容，但我们将在这里显示它，以便它不会感到被遗忘。它可能已经感觉比 configure.ac 和 Makefile.am 不那么重要，有一个很好的理由，它就是。一个名为 autogen.sh 的脚本不是必需的，您只需按顺序运行下面列出的三个命令，一切都将很好。autogen.sh 仅仅是大多数使用 automake 和 autoconf 的人遵循的一种约定。

  $ cat autogen.sh 
  #! /bin/sh
  
  set -e
  
  aclocal -I m4
  autoheader
  automake --add-missing --copy
  autoreconf

阅读 README.CVS，记住它，然后删除它，它包含的说明将在稍后使用。

  $ rm -f README.CVS

现在是时候进行我们的初始 cvs 导入操作了

  $ cvs import -m 'initial import' libraries/mincshazam mni initial-import

“mni”参数是供应商分支，而 “initial-import” 参数是与此操作关联的标签，这样您就可以在需要时返回到初始导入操作。

现在，请记住您在 README.CVS 中被指示执行的操作，执行以下操作

  $ cvs -d cvs.bic.mni.mcgill.ca:/private-cvsroot checkout -d m4 libraries/mni-acmacros

这将为您提供最近使用的 BIC m4 宏的副本。您现在应该有一个名为 m4 的目录，它包含 autoconf 用于创建您的包的 configure 文件的宏。

我们现在已经完成了创建初始包的操作，以下是您应该拥有的内容，当然除了您自己的源文件之外

  $ ls -F
  AUTHORS  ChangeLog    NEWS    autogen.sh*   m4/
  COPYING  Makefile.am  README  configure.ac  mincshazam.c

请注意，我们在初始导入后获得了 m4 宏的副本，这样我们就不会将它们添加到我们的存储库中。我们只是将它们作为自己的存储库在我们的存储库中使用。您在 m4 中所做的更改将被提交到 m4 存储库。（在这里要小心，如果您弄乱了默认的 m4 宏，其他人可能不会太喜欢您）。

从头开始构建您的包

[编辑 | 编辑源代码]

在这个阶段，您拥有 automake 和 autoconf 可以处理的文件，以形成一个 configure 脚本，然后是一个后续的 Makefile。第一步是生成一个 configure 脚本，您可以将其分发。下载您的包的源代码版本的其他用户将使用此 configure 脚本来创建一个 Makefile，然后从那里进行编译。从您拥有的文件创建 configure 脚本所需的命令在名为 autogen.sh 的小 shell 中。

  $ cat autogen.sh 
  #! /bin/sh
  
  set -e
   
  aclocal -I m4
  autoheader
  automake --add-missing --copy
  autoreconf

运行 autogen.sh

  $ ./autogen.sh 
  /usr/share/aclocal/gtk.m4:7: warning: underquoted definition of AM_PATH_GTK
    run info '(automake)Extending aclocal'
    or see http://sources.redhat.com/automake/automake.html#Extending-aclocal
  /usr/share/aclocal/glib.m4:8: warning: underquoted definition of AM_PATH_GLIB
  configure.ac: installing `./install-sh'
  configure.ac: installing `./missing'
  Makefile.am: installing `./INSTALL'
  Makefile.am: installing `./depcomp'

上面的警告可以（非常）安全地忽略。

这将为您生成一个 configure 脚本，使用适当的选项运行它（./configure --help 获取更多信息）。在我们的例子中，我们针对可以找到在 /usr/local/bic 中的额外库进行构建，并且还将在 /usr/local/bic 中安装我们的包。

  $ configure --with-build-path=/usr/local/bic --prefix=/usr/local/bic
  checking for a BSD-compatible install... /usr/bin/install -c
  checking whether build environment is sane... yes
  <...>
  config.status: creating Makefile
  config.status: creating config.h
  config.status: executing depfiles commands

假设上面的配置步骤一切顺利，请制作您的包。如果出现问题或您未能获得 Makefile，首先要检查的是您是否拥有最新版本的 automake 和 autoconf。除此之外，它就超出了本 HOWTO 的范围。

  $ make
  <...>

在这个阶段，您应该有一个看起来像这样的目录

  $ ls
  AUTHORS    Makefile.am  autogen.sh*      config.status*  m4/           stamp-h1
  COPYING    Makefile.in  autom4te.cache/  configure*      mincshazam*
  ChangeLog  NEWS         config.h         configure.ac    mincshazam.c
  INSTALL    README       config.h.in      depcomp*        mincshazam.o
  Makefile   aclocal.m4   config.log       install-sh*     missing*

请注意，我们不需要将任何这些 automake/autoconf 生成的文件添加到我们的 cvs 存储库中，因为它们都可以（也应该）为不同的软件平台和 autotools 版本重新生成。

发布流程 - 创建可分发的源包

[编辑 | 编辑源代码]

首先决定您将为您的软件包使用哪种版本控制方式，通常只需要一个点分隔的双元组。例如：1.02，如果软件包有许多增量版本，则偶尔会使用点分隔的三元组（1.2.03）。

一旦您有了版本编号方案，请按照以下规则集（严格按照顺序！）。

1. 如果这是您的第一个版本，请在 configure.ac 中插入您的初始版本。如果不是，请确保版本号与此版本正确。在本例中，1.0 是第一个版本，因此我们可以将其保留为上一节中的版本。

  AC_INIT([mincshazam],[1.0], [Andrew Janke <[email protected]>])

2. 使用当前版本的信息更新 NEWS，以便软件包的用户能够理解。

  $ cat NEWS 
  New in release 1.0 
  ------------------
  * Initial version.

3. 配置、构建并进行测试安装。

  $ ./configure --with-build-path=/usr/local/mni --prefix=/usr/local/mni
  $ make
  $ make install

4. 提交更改，以确保我们在其他人对软件包进行更改的情况下保持最新。

  $ cvs commit

5. 使用 distcheck 创建分发版。

  $ make distcheck

这将生成一个名为 mincshazam-1.0.tar.gz 的文件。

6. 在另一个系统上从该 tar 包进行测试构建。

7. 将 tar 包复制到您的分发站点。（在本例中，通常是 http://packages.bic.mni.mcgill.ca/tgz 用于源代码包。）

8. 为您的版本打标签，以便您可以随时返回此版本。标签应遵循以下格式

  <package-name>-<version number using '-'>

在本例中，这将转换为

  $ cvs tag mincshazam-1-0

9. 更新 configure.in 中的版本号，以防止其他人或您自己使用相同的版本号创建不同的版本。在这种情况下，最好只更新最低有效位。

  AC_INIT([mincshazam],[1.1], [Andrew Janke <[email protected]>])

10. 提交更新后的版本号

  $ cvs commit .


将二进制构建功能添加到您的软件包中

[编辑 | 编辑源代码]

我应该完成这一节

epm-header.in

向您的软件包的可执行文件和脚本添加 -version 标志

[编辑 | 编辑源代码]

空白空白空白


许可证类型

[编辑 | 编辑源代码]

如果可能，使用 MINC 许可证（旧的 BSD 许可证的修改版），或者如果您包含了来自其他地方的 GPL 代码，则使用 GPL 许可证。使用 GNU Scientific Library (GSL) 的 MINC 工具就是一个很好的例子。

这里还有其他类型吗？

迁移您的 cvs 目录

[编辑 | 编辑源代码]

BIC 的 CVS 原始位置（多年来）是 shadow:/software/source。这在 2006 年 8 月 23 日发生了变化，因此我们终于可以拥有一个公共的 CVS 存储库，以及一个公共和私有部分的 CVS 分割。

如果您有一个已检出的现有 cvs 目录，并且希望将其迁移到新服务器（cvs.bic.mni.mcgill.ca），因为您在其中进行了一些更改，那么您只需编辑您检出的每个存储库中的 CVS/Root 文件，以反映新的位置。这些文件应该只有一行，如下所示

  cvs.bic.mni.mcgill.ca:/private-cvs

我知道这可能会带来一些短期痛苦，但我相信这样做是好的，否则我不会这样做！

祝您好运，如果您遇到问题，请给我发送电子邮件（Andrew Janke - [email protected]）。

检索自 "https://wikibooks.cn/wiki/MINC/Tutorials/CVSandPackaging"
华夏公益教科书