跳轉至內容

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：a.janke@gmail.com。現在，我們假設我們要將我們的包放在 libraries 中。重新命名示例包

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

在 AUTHORS 檔案中放置包建立者的姓名和電子郵件地址

  $ cat AUTHORS 
  Andrew Janke <a.janke@gmail.com>

將您要使用的許可證新增到 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 <a.janke@gmail.com>])
  
  # 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  <a.janke@gmail.com>
  
       * 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 <a.janke@gmail.com>])

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 <a.janke@gmail.com>])

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 - a.janke@gmail.com）。

檢索自 "https://wikibook.tw/wiki/MINC/Tutorials/CVSandPackaging"
華夏公益教科書