1
2Instructions to create a full release of the ACPICA software
3and utilities.
4
5Last update: 12 March 2021.
6
7The build uses MS Visual Studio and Cygwin to accomplish the
8goal of releasing both Windows and Unix versions of the ACPICA code
9and utilities. For Windows, binary versions of the ACPICA utilities
10(including the iASL compiler) are created.
11
12
13Required Accounts
14-----------------
15
161) An account on github.com with full access rights to the acpica repository.
172) An account on the acpica bugzilla with write/change access.
183) An account on the acpica.org website with write/change access.
19
20
21Required Tools
22--------------
23
241) Documents: The main ACPICA documents (ACPICA reference, iASL user guide)
25are written in MS word, then converted to PDF format. Both versions of each
26are released on the ACPICA website.
27
28    MS Word
29    Word to PDF conversion tool (such as PDF Create 8)
30
312) Generation via Windows tools: The Windows binaries are built via
32Visual Studio. We must release the Windows binaries since Windows
33does not provide a compiler.
34
35See acpica/generate/msvc2017/readme.txt for Windows setup and ACPICA generation
36instructions.
37
38See acpica/source/compiler/readme.txt for flex/bison installation and
39iASL generation instructions.
40
41    Microsoft Visual Studio 2017
42
43    Flex and Bison:
44        https://sourceforge.net/projects/winflexbison/
45
46    Flex/Bison: probably obsolete:
47        Flex for Windows (http://gnuwin32.sourceforge.net/packages/flex.htm)
48        Bison for Windows (http://gnuwin32.sourceforge.net/packages/bison.htm)
49
50    PkWare pkzip25 (Available free from multiple sources). Here is a list of
51        mirrors: http://www.filewatcher.com/m/PKZIP25.EXE.339456-0.html
52        Otherwise, Google "pkzip25.exe" to find the free executable.
53        Install pkzip25 to /cygdrive/c/windows/pkzip25.exe
54
553) Cygwin for Windows: Cygwin is used to checkout the source code from the git
56tree, generate ACPICA from source, and to build the ACPICA release packages.
57
58    Cygwin is available at (http://www.cygwin.com)
59
60These Cygwin packages are required for ACPICA generation:
61
62    git (found in Devel)
63    make (found in Devel)
64    gcc C compiler (found in Devel)
65    flex (found in Devel)
66    bison (found in Devel)
67    m4 (macro processor required by bison, found in Interpreters)
68    dos2unix and unix2dos converters (found in Text)
69
70Additionally, to write to the git tree, these are needed:
71
72    openSSH (found in Net)
73    corkscrew (found in Net)
74
75
764) Windows/Unix line termination issues:
77
78a) Install Cygwin with the default setting of CR/LF line terminators
79b) Ensure that these lines are present in the git configuration file,
80   .gitconfig in your home directory:
81
82[core]
83        autocrlf = true
84
85
86git and ssh stuff
87-----------------
88
89To write to the git tree, you'll need to setup an ssh connection to github.
90ssh clone path is:
91
92    git clone ssh://git@ssh.github.com/acpica/acpica.git
93
94
95Build the ACPICA Software
96-------------------------
97
98Cleanup any extraneous files in the local git tree
99
100Complete any updates to the ACPICA documentation (ACPICA ref, iASL ref)
101Create the .PDF versions of the MS Word .DOC files
102Checkin any changed documents
103
104Update the version number (hex in the format: 0xYYYYMMDD)
105    in the file source/include/acpixf.h
106Build Windows debug versions of all software and utilities
107Build Windows nodebug versions of all software and utilities
108    (generate/msvc2017)
109Build Unix versions of all software and utilities
110    generate/unix/make clean
111    generate/unix/make
112
113NOTE: The following steps are obsolete, not used, but this is how to do it:
114        Generate sizes for the acpica library from generate/release/size.bat
115           Note: This step uses MS dumpbin(link) which is a part of the VC package.
116           It might not work unless the environment variables are set correctly.
117           Execute VC/vcvarsall.bat from the command line if necessary.
118        Sizes appear in the files size_rel.txt and size_dbg.txt
119        Integrate code/data and debug/nodebug sizes into the release notes.
120
121Write the release notes
122Add the release notes to the documents/changes.txt document via Word.
123   Note: From Word, use "Save As", then check the "MS-DOS" and
124   "Insert line breaks" boxes before saving.
125
126Checkin documents/changes.txt, message "Logfile: Changes for version yyyymmdd"
127Checkin the new version number, source/include/acpixf.h "Update version to yyyymmdd"
128Git push everything
129
130Tag the version file with a name of the form Rmm_dd_yy
131    Get the commit number for the version number commit above (git log)
132    git tag -m"version yyyymmdd" Rmm_dd_yy HEAD
133    git push --tags
134
135Build the various tar/zip release files:
136    Convert the generate/release/.sh files to unix format: dos2unix *.sh
137    On cygwin, execute generate/release/release.sh (sh release.sh)
138
139
140
141Update the ACPICA website
142-------------------------
143
144Login to acpica.org (with update permission)
145
146Create a new download node for the new ACPICA version:
147    At screen top ("Manage"), Goto: Content->AddContent->Downloads
148    Title: Use the new version number in the correct format (e.g., "Version 20210105")
149    Body: Insert the release notes for this version
150    Date: Must be the current date (should match ACPICA version)
151    File Attachments: Add all of the release zip/gz files (currently 6 files)
152        (From the acpica/generate/release/current directory)
153        Currently, no need to add a description for each file.
154    Click "Save" at the bottom of the page
155
156Update the version number token.
157This will update the version number header on all pages where the token is used:
158    Goto https://acpica.org/node/88, click edit, update version at body top
159        Click "Save" at the bottom of the page
160
161Update file pathnames:
162    Goto "Downloads", click edit
163        Update paths to new file versions, update file sizes (3 files)
164        Insert the release notes as the summary
165        Click "Save" at the bottom of the page
166    Goto "Downloads/Windows Source Code", click edit
167        Update paths to new file versions, update file sizes (2 files)
168        Click "Save" at the bottom of the page
169    Goto "Downloads/Windows Binary Tools", click edit
170        Update paths to new file version, update file size (1 file)
171        Click "Save" at the bottom of the page
172
173ACPICA document updates:
174    The documentation/changes.txt file must always be updated.
175    Additional ACPICA documentation may require update (in doc/pdf pairs):
176
177        acpica-reference.doc
178        acpica-reference.pdf
179        aslcompiler.doc
180        aslcompiler.pdf
181
182    Goto the "Documentation" page, click edit.
183    Attach/upload all new versions of the document(s)
184    Uncheck the "Display" box for each new document
185    Update pathnames (and file sizes) in body for each new filename
186        (appears at bottom of each attach)
187    Update "Last update" dates as needed
188    Click save at bottom
189        <Note: this may be fixed so that the filename can stay the same>
190
191Update "news" if there are any major changes or major new features:
192    Update front page news:
193        Goto ContentManagement->CreateContent->News
194        Add news item in the "Title" section and click save at bottom
195
196
197Cleanup:
198    Convert the generate/release/.sh files back to DOS format: unix2dos *.sh
199
200
201Email the release notes
202-----------------------
203
204Send separate copies of the notes (in plain text) to the following:
205    AcpiCa (acpica.intel.com)
206    devel@acpica.org
207    acpi@linux.intel.com
208    CaClients (undisclosed recipients/BCC: list)
209
210
211Update ACPICA bugzilla
212----------------------
213
214Close any problem reports that have been resolved.