From 7c72e995df2af5ea9591bdfe6044b8223fbd4f2f Mon Sep 17 00:00:00 2001 From: Jeff Scheel Date: Thu, 1 Dec 2022 15:05:37 -0500 Subject: [PATCH 01/17] Add zstd-dev library to fix gem install asciidoctor-mathematic Fix for Issue #8 Signed-off-by: Jeff Scheel --- dependencies/apt_packages.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/dependencies/apt_packages.txt b/dependencies/apt_packages.txt index bdf2ce0..0682bde 100644 --- a/dependencies/apt_packages.txt +++ b/dependencies/apt_packages.txt @@ -18,3 +18,4 @@ pkg-config ruby ruby-dev libwebp-dev +libzstd-dev From a76f651eacba3f1b5ca65847a9403a3d95cd70b9 Mon Sep 17 00:00:00 2001 From: Rafael Sene Date: Thu, 9 Feb 2023 11:34:06 -0300 Subject: [PATCH 02/17] Update readme.adoc Add the steps to build from a base container image Signed-off-by: Rafael Sene --- readme.adoc | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/readme.adoc b/readme.adoc index e90f06d..15df15c 100644 --- a/readme.adoc +++ b/readme.adoc @@ -51,3 +51,29 @@ in the PDF build fail with an error message like the following: = Building the document The final specification form of PDF can be generated using the `make` command. + += Build the document from a container + +To avoid dealing with configurations and dependencies, you can easily build this documentation from within a base container image which contains everything you need. Here are the steps: + +NOTE: https://docs.docker.com/engine/install/[ensure you have Docker installed] + +``` +$ git clone https://github.com/riscv/docs-dev-guide.git + +$ docker pull riscvintl/riscv-docs-base-container-image:latest + +$ docker run -it -v $(pwd)/docs-spec-template:/build riscvintl/riscv-docs-base-container-image:latest /bin/sh -c 'make' + +Building asciidoc +asciidoctor-pdf \ + --attribute=mathematical-format=svg \ + --attribute=pdf-fontsdir=docs-resources/fonts \ + --attribute=pdf-style=docs-resources/themes/riscv-pdf.yml \ + --failure-level=ERROR \ + --require=asciidoctor-bibtex \ + --require=asciidoctor-diagram \ + --require=asciidoctor-mathematical \ + --out-file=example-spec.pdf \ + header.adoc +``` From 0a5e626337b26c98c9194c8c3857405aa6bb43c1 Mon Sep 17 00:00:00 2001 From: Rafael Sene Date: Tue, 11 Apr 2023 10:09:16 -0300 Subject: [PATCH 03/17] Updates to fix the build issues Signed-off-by: Rafael Sene --- CONTRIBUTING.md | 40 +++++++++++--------------- Makefile | 24 ++++++++-------- dependencies/apt_packages.txt | 12 +++++++- dependencies/package.json | 7 +++-- example.bib | 52 ++++++++++++++++------------------ header.adoc | 15 +++++----- images/risc-v_logo.png | Bin 0 -> 32482 bytes images/risc-v_logo.svg | 1 - 8 files changed, 76 insertions(+), 75 deletions(-) create mode 100755 images/risc-v_logo.png delete mode 120000 images/risc-v_logo.svg diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ab2007c..3c79557 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,26 +1,23 @@ # Contribution Guidelines -As an open-source project, we welcome and encourage the community to submit patches directly to the project. In our collaborative open source environment, standards and methods for submitting changes help reduce the chaos that can result from an active development community. +As an open-source project, we appreciate and encourage community members to submit patches directly to the project. To maintain a well-organized development environment, we have established standards and methods for submitting changes. This document outlines the process for submitting patches to the project, ensuring that your contribution is swiftly incorporated into the codebase. -This document explains how to submit patches to the project so your patch will be accepted quickly in the codebase. +# Licensing -## Licensing +Licensing is crucial for open-source projects, as it guarantees that the software remains available under the conditions specified by the author. -Licensing is very important to open source projects. It helps ensure the software continues to be available under the terms that the author desired. +This project employs the Creative Commons Attribution 4.0 International license, which can be found in the LICENSE file within the project's repository. -This project uses the Creative Commons Attribution 4.0 International license, as found in the [LICENSE](https://github.com/riscv/docs-spec-template/blob/main/LICENSE) file in the project's repo. +Licensing defines the rights granted to you as an author by the copyright holder. It is essential for contributors to fully understand and accept these licensing rights. In some cases, the copyright holder may not be the contributor, such as when the contributor is working on behalf of a company. -A license tells you what rights you have as an author, as provided by the copyright holder. It is important that the contributor fully understands the licensing rights and agrees to them. Sometimes the copyright holder isn't the contributor, such as when the contributor is doing work on behalf of a company. +# Developer Certificate of Origin (DCO) +To uphold licensing criteria and demonstrate good faith, this project mandates adherence to the Developer Certificate of Origin (DCO) process. -## Developer Certification of Origin (DCO) +The DCO is an attestation appended to every contribution from each author. In the commit message of the contribution (explained in greater detail later in this document), the author adds a Signed-off-by statement, thereby accepting the DCO. -To make a good faith effort to ensure licensing criteria are met, this project requires the Developer Certificate of Origin (DCO) process to be followed. +When an author submits a patch, they affirm that they possess the right to submit the patch under the designated license. The DCO agreement is displayed below and at https://developercertificate.org. -The DCO is an attestation attached to every contribution made by every author. In the commit message of the contribution (described more fully later in this document), the author simply adds a ``Signed-off-by`` statement and thereby agrees to the DCO. -When an author submits a patch, it is a commitment that the contributor has the right to submit the patch per the license. The DCO agreement is shown below and at https://developercertificate.org. - -``` Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: @@ -38,7 +35,7 @@ By making a contribution to this project, I certify that: in the file; or (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified + person who certified (a), (b), or (c), and I have not modified it. (d) I understand and agree that this project and the contribution @@ -46,19 +43,16 @@ By making a contribution to this project, I certify that: personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. -``` - -### DCO Sign-Off Methods - -The DCO requires that a sign-off message, in the following format, appears on each commit in the pull request: -`Signed-off-by: Stephano Cetola ` +# DCO Sign-Off Methods +The DCO necessitates the inclusion of a sign-off message in the following format for each commit within the pull request: -You are required to use your real name in the sign-off message. +Signed-off-by: Stephano Cetola -The DCO text can either be manually added to your commit body, or you can add either ``-s`` or ``--signoff`` to your usual Git commit commands. If you forget to add the sign-off you can also amend a previous commit with the sign-off by running ``git commit --amend -s``. If you've pushed your changes to GitHub already you'll need to force push your branch after this with ``git push -f``. +Please use your real name in the sign-off message. +You can manually add the DCO text to your commit body or include either -s or --signoff in your standard Git commit commands. If you forget to incorporate the sign-off, you can also amend a previous commit with the sign-off by executing git commit --amend -s. If you have already pushed your changes to GitHub, you will need to force push your branch afterward using git push -f. -**Note:** +Note: -The name and email address of the account you use to submit your PR must match the name and email address on the ``Signed-off-by`` line in your commit message. +Ensure that the name and email address associated with your GitHub account match the name and email address in the Signed-off-by line of your commit message. \ No newline at end of file diff --git a/Makefile b/Makefile index e6f515d..eaff0cd 100644 --- a/Makefile +++ b/Makefile @@ -1,21 +1,21 @@ HEADER_SOURCE := header.adoc PDF_RESULT := example-spec.pdf +ASCIIDOCTOR_PDF := asciidoctor-pdf +OPTIONS := --trace -a compress \ + --attribute=mathematical-format=svg \ + --attribute=pdf-fontsdir=docs-resources/fonts \ + --attribute=pdf-style=docs-resources/themes/riscv-pdf.yml \ + --failure-level=ERROR +REQUIRES := --require=asciidoctor-bibtex \ + --require=asciidoctor-diagram \ + --require=asciidoctor-mathematical + all: build build: - @echo "Building asciidoc" - asciidoctor-pdf \ - --attribute=mathematical-format=svg \ - --attribute=pdf-fontsdir=docs-resources/fonts \ - --attribute=pdf-style=docs-resources/themes/riscv-pdf.yml \ - --failure-level=ERROR \ - --require=asciidoctor-bibtex \ - --require=asciidoctor-diagram \ - --require=asciidoctor-mathematical \ - --out-file=$(PDF_RESULT) \ - $(HEADER_SOURCE) + $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE) clean: - rm $(PDF_RESULT) + rm $(PDF_RESULT) \ No newline at end of file diff --git a/dependencies/apt_packages.txt b/dependencies/apt_packages.txt index 0682bde..6ddd571 100644 --- a/dependencies/apt_packages.txt +++ b/dependencies/apt_packages.txt @@ -1,21 +1,31 @@ bison build-essential +python3-pip cmake curl flex fonts-lyx git graphviz -# For wavedrom default-jre libcairo2-dev libffi-dev libgdk-pixbuf2.0-dev libpango1.0-dev libxml2-dev +libglib2.0-dev make pkg-config ruby ruby-dev +libgif-dev libwebp-dev libzstd-dev +ruby-full +gem +npm +texlive-latex-base +texlive-fonts-recommended +texlive-fonts-extra +texlive-latex-extra +texlive-science diff --git a/dependencies/package.json b/dependencies/package.json index 9d80afe..7347d43 100644 --- a/dependencies/package.json +++ b/dependencies/package.json @@ -1,7 +1,8 @@ { - "name": "local", - "version": "0.0.1", "dependencies": { + "bytefield-svg": "^1.8.0", "wavedrom-cli": "^2.6.8" - } + }, + "name": "local", + "version": "0.0.1" } diff --git a/example.bib b/example.bib index dd4ca0b..9da24b1 100644 --- a/example.bib +++ b/example.bib @@ -2,39 +2,35 @@ @inproceedings{riscI-isca1981 title = {{RISC I}: {A} Reduced Instruction Set {VLSI} Computer}, author = {David A. Patterson and Carlo H. S\'{e}quin}, booktitle = {ISCA}, - location = {Minneapolis, Minnesota, USA}, + location = {Minneapolis, Minnesota, USA}, pages = {443-458}, year = {1981} } -@InProceedings{Katevenis:1983, - author = {Katevenis, Manolis G.H. and Sherburne,Jr., Robert W. and Patterson, David A. and S{\'e}quin, Carlo H.}, - title = {The {RISC II} micro-architecture}, +@inproceedings{Katevenis:1983, + author = {Manolis G.H. Katevenis and Robert W. Sherburne Jr. and David A. Patterson and Carlo H. S\'{e}quin}, + title = {The {RISC II} micro-architecture}, booktitle = {Proceedings VLSI 83 Conference}, - year = 1983, - month = {August}} + year = {1983}, + month = {August} +} @inproceedings{Ungar:1984, - author = {David Ungar and Ricki Blau and Peter Foley and Dain Samples - and David Patterson}, - title = {Architecture of {SOAR}: {Smalltalk} on a {RISC}}, - booktitle = {ISCA}, - address = {Ann Arbor, MI}, - year = {1984}, - pages = {188--197} -} + author = {David Ungar and Ricki Blau and Peter Foley and Dain Samples and David Patterson}, + title = {Architecture of {SOAR}: {Smalltalk} on a {RISC}}, + booktitle = {ISCA}, + address = {Ann Arbor, MI}, + year = {1984}, + pages = {188-197} +} -@Article{spur-jsscc1989, - author = {David D. Lee and Shing I. Kong and Mark D. Hill and - George S. Taylor and David A. Hodges and Randy - H. Katz and David A. Patterson}, - title = {A {VLSI} Chip Set for a Multiprocessor - Workstation--{Part I}: An {RISC} Microprocessor with - Coprocessor Interface and Support for Symbolic - Processing}, - journal = {IEEE JSSC}, - year = 1989, - volume = 24, - number = 6, - pages = {1688--1698}, - month = {December}} +@article{spur-jsscc1989, + author = {David D. Lee and Shing I. Kong and Mark D. Hill and George S. Taylor and David A. Hodges and Randy H. Katz and David A. Patterson}, + title = {A {VLSI} Chip Set for a Multiprocessor Workstation--{Part I}: An {RISC} Microprocessor with Coprocessor Interface and Support for Symbolic Processing}, + journal = {IEEE JSSC}, + year = {1989}, + volume = {24}, + number = {6}, + pages = {1688-1698}, + month = {December} +} \ No newline at end of file diff --git a/header.adoc b/header.adoc index 3f06ee1..9c80801 100644 --- a/header.adoc +++ b/header.adoc @@ -1,7 +1,10 @@ += RISC-V Example Specification Document (Zexmpl) +Author 1; Author 2; RISC-V Task Group + [[header]] :description: RISC-V Example Specification Document (Zexmpl) :company: RISC-V.org -:revdate: 1/2022 +:revdate: 1/2023 :revnumber: 1.0 :revremark: This document is in development. Assume everything can change. See http://riscv.org/spec-state for details. :url-riscv: http://riscv.org @@ -10,7 +13,7 @@ :colophon: :appendix-caption: Appendix :imagesdir: images -:title-logo-image: image:risc-v_logo.svg[pdfwidth=3.25in,align=center] +:title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center] // Settings: :experimental: :reproducible: @@ -36,9 +39,6 @@ endif::[] :footnote: :xrefstyle: short -= RISC-V Example Specification Document (Zexmpl) -Author 1; Author 2; RISC-V Task Group - // Preamble [WARNING] .This document is in the link:http://riscv.org/spec-state[Development state] @@ -62,6 +62,7 @@ include::contributors.adoc[] include::intro.adoc[] include::chapter2.adoc[] -//the index must precede the bibliography + +// The index must precede the bibliography include::index.adoc[] -include::bibliography.adoc[] +include::bibliography.adoc[] \ No newline at end of file diff --git a/images/risc-v_logo.png b/images/risc-v_logo.png new file mode 100755 index 0000000000000000000000000000000000000000..4e826b2d2ff2e5ed8a5f8e6305618684aa79470e GIT binary patch literal 32482 zcmeFZ_dnJD|37{|h!p9lRA$*qL^h!!krk1Wh^#U~Mj0I`jue$uwo)nzk&<-^DH09Y zBO_%;_WIuL=cw1~_5R`e7kpeUJ)h3waUZvNy^Z_*2sPB#VqL|#3L(U*eL%wqp%tPC zG0?4KgeO^_IGo^r%x4cA^*~5M0RJQS+*k8LXbaNT*mKyYd9Y2&o$F|fMCX@v&c_X; zzlRE|jIH3<@`27}z4w+st5)%tky2Ldyn1X;s_D*CRs_}^q~975?Kj#dcz?Yfu;0>j zcZ(4nGfCYp!1D6mwq5NVs{}{;3Z~|VI+hl_5t@)r_FBW=rNG~=LysDtM^&4xq8wb% z+rx||OrxWjazwXB#4M^ttwq_+VzHRt>#LP(}Hh;FOCyShsA!<4s3?In@*zEOPM~X{f8^dyXJ#~i`4YQX$R&0( zeZT+qwExkj2=bH>0S${S58wDGJfve|%)(h2ZglM69_Gw_K$26rU-Nl0)5(1&nbDKf z6ozl`59QyD%O2D!chlh3VL);JhFU!L=~F1#5c6O=A!X0{D2mehC`8G~c(6SpLrv~7 zy?V{xof01pKP{5n&a;Av#A!rh1o_&i4smOgr_994 z16@^zTKNbsteDW`jb)A=UT12dgnTd2L5*CibgXz*>7bOD$8+04augU{9%C`NxTn;by60cUd zawwvB{S~n3Z3E>XGhLICSVrU&vrLOabbnHno9H%zl?|4`;z0(aULBxbV z{9XI`VXOsABWa}_7bd!`CnocE>Enky;Xd?e{*7O=BAM)_;dg@(&A%hMTJZ>r5>UXx zy#b|O>6KyU5VGplHKao-U;LUkms{Wb$mNJg%sN)P@vx*N0Vj4M6Y=*^PFRo^?|lZ? zTrkr$=GCDmL_%%TWOk4JF3pOVm_6 ztW9FVZ?n>x|15M6-2_-+DwsVgx*Jt3&Y@LOd!K+1UinC@dx2g7ccpdU8iexV@akHR zS12usaL+KJlnT6va+LcFXSg3ds_h12wKo{RFgi;>iy?iBl zr9;U}>tgy4s#C|?aULk}yIxToCI1=5XyY-mhoYn8Fgc>s_u2)mZ>?{Qh2b^nU`_R! z!(1hE#NV;-;Gr^ppm+Z`V`>@$O8G&ZZWC<5PsBSI(wV(Ry7V5A2@zb5uUp4Tr>eOGs?NFT|^;dQLs}=rrG7%U~`5px% z5AMQrtUfH%Yp)H~;fm?lanpVC{&GuT-6|PS2OSdxBNGw=8BiCNHqoBZWQVErc&ajw zR{8x+VD+-ph3+4B5xC1o^ahz&#Zni$5Byp2QP&ag9h2p#EC$;Vp}vZBzoS{M1{_l) z@OyGpwIILhL14Jy0cdOsKfjSg8CfBg0n9}kh^OoeBEMV@#+apvKV3W=U(9qeR~|lN zx+va{Yuf37iBV3x`23b$cMc*JCnXwh#qh^Hcwx!=$MwtnVVF}O$c<#e`iA=9HvSO(G6MeVj7=*0S-)zP z0hXFEb53EiX78VdIBNhK#A+aHS%ynTg77aaiY68rFMjCJUn)JiQ7 zlvxnoWaB}wq`M$T(#Au0qnN1bqYC}3h_V_l)p&Ui?E~J$EdE|QtQLi*T|fJk3z1@} zv}u=7KiE@0NQuP`kT+pLn@|^c7**}4aa;#~#%nYN2d)IKyh2^$AQ(Bh7U=3cg6VXs zRuKOH0I`w!L9?n?j>8=2?9|3Y=L`2rGp~jiJRMpZhI}5mxPFZwU(~)7JUjMoY3Phb ztLf5A{_F^m_~OV$5lc-*1I`O4KwnX%3v(SyF?6H+t8{$6+WKvmES;O{@9HsC$*cEk zzN1mjq>W^Zt9o6H(1|JlDyMHJC#L3lm$Y8UzY5bldER2-&XulPlbdk-Dk82xi0w`a z!-)?JLQWt2-4rtx7cY3ax$oeJvr`?qCeU?H5XDt8&_Fob*VS6eZ6^6qwTtVybsaj@ zca$X@$zRM`wH&X40GD>|VJ^DOtm9+ieJDCQH9PI?k1rp$@GnL&sOR3M#g-Ggdzh6y z*M&VB6X&>c-&g$6^_e^m9^!}~p^h5|8h~&0-Nj)Q`+L}k#J2XIDkag;4P7T|ua~U{ zhuW|%iV}7w<#Ms-W@02+!PxX!7VIF-+vLTjz8jeM_S=#lk=`m^BSVn5SXlh&=nHwy zbH4XpSf8xDriqX`BmgLG_=Oqw{o>)t{gJ1~HhTeVgpnmdVHBPyRJX?U?yKBqEnICH z<&GM<;teM&-+q6*7LmT~0?Qs6m*CK%jHGX4(|99s`!2W~h6`seHItdrwswaf)AGvF z9DqlKU?n7Sgu18 z3N-(r?CzKux6>yx@Z+I0aBS1x68wvm(meV1PjE1k`=uwI@1K0y@9lT*tG==01Ad8M^0GIX$)V4*vx z0t}9Ft`X?USfQlyMFV)QNr&A|R4>r+Xn7yi#%}J72g>1r%>g5m`*)d_9Q{NciDA#{ zyT5q2A7AJt%bjkkQQcX*{gHOf^2`>l3C-8WMiLDtkFG)L_pqcbF03Oi^-u1nKQy`y zGa(a;nP9qjEUC;`yqZAUBwG@1vQBE0VMz`lP930qFp^D2C#kbz1ybLK*YO`uZQ-hU zRs6~P&{;_UX?_U+raBe8HD7T=MX;-o5SyL`=!E*nk|+4qt&#tHP8JiJiHNFp)<^(I zNjVD0Kq*naMmCl*R9pu(k&6|hl-(9jCLbu!g}jCxWP(F-|6c9)yNy8~tXLoYJ^R48 zucl65WT8Fz5rJ)OpYQ$SAKys1f+Jw`^88~DGH2hHaR&_6VI@e>@JKGW@0Q?i)G&!% z;$en7(e2yN_4ccG{kg{(kps>R4edjSZrg&tNoztJ#HO1v>@?{j32)TtF^R&{_dvuI zbxONHl3$Zy8HZI1!> z!3?az6Pn5ciXyr}5FyQCvh-w#domP$up&bnyh`XAaAq?WoPVQ-Qb0o8VLqM-myoFH z2J*{DaEaY`E#Y`_imV-^fe%ISkW=9oUWC{HyvyE)X>l%%L)X`o*ZEM%jl|@>0@MDe<&IJHa-;clmL*fy1A}KozHM8Y`qn)%P}JU!LjHLU_Nca z`|K93;tl(D;aJ{f1lpRw`f2Xb)3{bq=Rn;q3~v|T0ZasL;vC4pQ?XO#fsa#mkK?q<$VD&l6a_q6G0b4TU!-9CCdq^(U7qH?qj^TMtFdsw2Ln0>3?tv(m zXs>i69a8tl>*aHiQ*M@!fel{FMhh$KZ!RShPL&B3W%IC}26tGh8#Wx-Ylied zF3FX9+$H7=*vFt65J-_90iU_KDQ+v3NXjBM2*29(wz;i9q*W>C5S8@tR@oH*Hc|qp zZ%6cA$Qv2SRq6sV%wc?l^w`$pc-Y_Z0cj~t;nW@E@eUEN;mY_T!ikE4l_XpPBHo6L zdu&=mkyS==4!sn@H6v2_$YAT?w}C*JOo|nYHUIl`*aD-|J^`4P-<_KwLoG6qO3ixP zUAG4bjYZW_)rKsz>?G;i#ytWM(;CI6^y#>;efc!I@;fjU*I!C?{p1|L*!NQ zAnq69C!7?+)_W)UqIXAS{IlnzC}P6x-Nfhqy2XP8Uo; zG@Bl*VxeVSrFBEs!_y3XV-!(Qt8JC7DC6>Tpk+w$*2+=o;Y5afeJrCh!lDBs#~6^L zw0^(~s*{Ag6dtV8a?ssLm9cS&KL^U8`vH+K!7;a(U8^ zw|1;9T7{pVUZa835Bg17Gx_LY#n!(JdA2yLfkqF408=-S8n6|bUBC2f(J6Jsv?2&a z8QYUt4Wvd6FWssts<}Jsv3^a*^%4 zLngd#bB_^&I+yBzk;FbJZO)f2HiQA!dBQsxp2 z2efibaG%-6m@-Udz+(p;nxves>OIV&z7A87)CaaUc>7+P`aK#^CumZP!+{_0@HdsE zIzg&HuyZTBQ-$Y1wYgo#EfS6&OihARE^s}G(_=)i&Wy@@mpX&`_3OqGmK8|mCe;jL z`H>Y9&2ZwdnPe+*854Y*!@cOQV~;U|LXFe_hVy%#z=@TSt>k^N-rSNwy@sYg8C=O( zc?z2$pB*&ArB=6@A0bW7dJRI&!1SBiUwYQweic0o1;afkl_HC|-u~*9!f%_L_HYgK zb(!~g>R=BrqWlk_&S*R=qksdPv5R%EusbSjK!fxRS0I^o!k3zr*AucURnw2FoFSQF zm1O<^p*g*$I&#Vr>fD?y={RKuDeUfT*G{2^_U+lP3n#(*1|I=2yBHmC-AKvuClZi3 zP1ki^Sge-2nv5=jm-xQ@&mqNPJMi=9_VK>=@*=wr zYoA!Gu@owz3V{pH2iZz%6%yod+hO!N^KCn+JPUPfS-h=9%>ImjdyFs zV()B1->6o;m#>%7Ub z2Q3*WG1sWRm8}R$LzRW`@1V>B!Zy~jkXUi>eX^9}sHmR{P1F}eH&JG*G7wlJI|!`K zOZa3Q-j5ZBt3X|8GTqf*dK!63FL%f)FC%?CFdj1e2|1O#xbV|{4gUv zBP=p>6X&nul_XZT5kboKzv<5ShjgAP13E5$)3oCyR|!^yK({*Aog}BHB`{RcpujAR zadZ{+;dRYAGcbCtP6v6)cI;HnHW!{X&GI9;PK93g?Tn-bY$Y6k4Rj`+Yj zuJ#glXGJm})!+uhu|!^dudfK@OJbEv_6q0kN)#k*oTho|3(RX|qNPPbLTKu5yjZ7n zZ&!ddX*ag^xPA%ow~k?fD@hww1pK_vATws|uuYg-95jlHu9Np^qgwy{G+C;F6_bQ# z-N6r}^p(xR=~Wue1FXZd+6Td$>c8pi)M&#W|ea z$-JMbuXwM)^5osRZbpz^V_9!GlZ4w zKFrcOKfu&Gp{XXi26P#m=~QK3#QVOQ0|KQv_6>mlnJi1R1J6ioyL|VtC-}8#kAu9r z9;R7oX;j5)@H$}i2)tL=i=zDS>9hlg4m z->=bOlrR|w-C?qi2y-Vh&8xp+Nj#+IDhxgAv~GIF;|<7D5A&ro|8o$ucs%TGF~EGw z*(JfzJiyafGg^r<+2pVIOI0ddpzHc3k`^su8CrrRSy_sSoPX!e-6<6-wlSFv$zr#k zyy<>x2|z{*`)21&`wDdyG(mmwnR*0?^A!0M2>UPA5F=cRFuVBZcm~Out4B0(2 zP_)AyH@8>uy$vWJVz(rtHLdc?mQ<6Aj#RPRLTB}!rgUok=`|$HA08Dc9uGZ#D!YL+ zsmAq=K+Wa#Q<@_(Quw6L2XzKYnf?B%isx*I73XSRy;&gez)e0M{F;Ahm4m=HK(Zur zTc8~pnSMt4W2+ba5gWw$r*s4dQOKYvXI_PoUxR_&5%sB}w({9-p=~tT%EU55o8x(F zhy0_2o+EGh(KZPF)Q&V@YL2J~Pi=QPmhH~n%zhpT?l}ioQ@(TmW<>cz$$(DbKXSHl zT?q80fq)DyS{q~H$qI6^?;k(@rM*IEEfH+t_jy#ujt>%AMvrK4gXkZeghm;CUJ@9@ zvA2*aWdG)i=J-B({DDXyHSWAb$I9_zu|A?(N>0c$W^>2)gxfQ7?2EE=O@IM-3Bw9vSg zC86KS_V&T;BnEJ=6NgbARf>;?BRsZ?G?Af~wwA~zM0oO}T^r#8j?zCz#2*M}X}%7= zu8CBcjBqMd=K>bhDQ0QyR-48b?$inbzDj1hMKV=3D7an4gl%QM^Psq}u>D=DuqgIA z7ZC6$E2ja=-*pNq+tuP}#P$Q%y4qLmGd)>X= zBMXQL@{451`$o-m5HA2V90+aNU;Yb&$oiuEnY?j1r{Q2ZNc~U*eybd?HmTz7?Yx`u z7Mxn;TvF=3YV_dR`_Mcluf~&?X#YT{iD}%iPn16(mLYHIP83e-Q3OD>dhYSJ)`a&x z{axi=hbKd=>6)uQxu5_n!U=C)Vy>C)!4qLY{=1UB7^#dLgBT`RgM4se+~2pT|Nf}B zj<(utqj|kG_m{}J6Es^H-31bO7$W)m$&EZKl9D28m|Myd8pMrmhgXdTQ&)Nh`@2pF zujzMC9r`2C6(pDvJ?C}&8aLfmJt)tKTe7?$-pAnftf=;S=b&cF&rmL~o=USQP7zvtQPu29f zbwsFYN1=HN8J2&O&q&GHB5%vR?QxeckLYTkC$a|$TCYO45M14P@)yu2&Pb}cW1!qk zR)}KA8!t4WYAk7>6j}@vVW(_WA@|zqOv|FGpKn6c zgIRP2mV=W$3-&r4@X^psh%Id*<{V32y#;hx0!4J+oZ6ke6^nsamg+_6f+^2~ z#bVFEv=*-G0$s&|Bt4vKj0T;ynYsfnKN?G{qrT+PEZ5RT@fb}zmFwRQYb(5Ba`wck z$5V@0C9_C7Fqmf#ii=kS%5h=wQUvq`x)L{$^l;KK%2)r^W$Nl4Uw<8_V=2#|0mvQm zfMAY0Rd8?wh}jrn;P4#kKQk6_HPQ7@w$bha0KZH*FK6kkwqusyEPV6j`%HCq-b6QX z#-yFhQ|$ESm@0>Y#|iVsfC^N@FoRy=+wc8sR@HdY4xG?f=lnqqS>sXF8dMoB?6hDj zq8{=cH0kXT=WYp-D-0zEZo)I$gMCE;k6_9iw)P4dZl*CKO#H3SLOFxE%)92!{?P9) zBQj(%q$fod>*f+eGXkTCzGkFC;5)&>JYMmdqg? z!ChnrLa*Q`g=#@D(6rC#W5`|&nj!@o>(jA81|n>21!oEUT38K*IO}rQi6`i3u+W5g zQB8`Xk1GVu(~wnMc4wcqqZ!g|jdEq^S&Vt(c5^MpT1`dAPlUC^-(tAT$5yz7KOmAJ z`yf7h=G?EyEMA~naIJ!>qP4{ITgVF+vUOXkw5{IL>?q;<2{easux>55h(c5(W$Hgx zRK`<5Ny0*sp@6P5%9k)LKU8|9iFmI=YW%7?bd4J^YjF_A%gEEl>=gR{IE0xKr1)I< z5c|G1{yj@N$cU5FQ8LxdvJJ3GWo44R+TU6iy!LfO2UYJMx1)-OQvf|1bpYFanx9?Ag)NV5m>0 zCXX>OPz!qN;2!=sWoq2VHXQ$_jD7l!0j{gC6+&=`7bGd2E$2d35r?&2833ZokSt&R zEpk4EwEDz`655v#Z?p0*Yw7czIz(LjbBYS2; zc}$VlL#5BVnWrujGX9&D4k5zV>&!YSHQZrzUSLgsY;x|K!vg&nN3j)N;3C@JqMl{v zHJyARA4euMUYW_;1&7~PcC=B(S&X28)k%yzJ0fUkyh7D~Q}apaP`xFkv%ftCP`10*!F{-DhCrMJ9L?wre=(xZr zW??ETbPN8e4)~RM-GRG#WoF!wZr4`%+{F0+hj-x2ryCj zFCqjC?c}#3p1j3=%!yigIKG@(-Izp!#Ehpr&q%Be;*kAjC=O2U57?=`+GO=v;hdND zMvBZ%)ij{#7p%P_ND>A>&m7+OT$bn%$h7)w$^LStP-HH*Y}9X}`PIuHE++L+PlM=X z8iK6HlsHzOofl=uA2P<_KE_0{Qg4LXGV>`hjxSC@dmRTDOY9+|y)|OOfxCC=790}=P|*SmxYd5Q#do&TZe$Su?i88hWVKt}sndS4f?^1d%01^E}{0nJ?C z@Kv2fJVU=P0rUhNSIR6_=wt%`8sPg;jrr|BZ@?y6T=@7VT0ng@blkExU-W|GRwy;@ zh+0kI8i2g%t@Ykti5jHcV`9Bsb98DyC-;|uj+s-gLvrl&5qwFBoqq6RkWK57BuAJl z?5(;CzWvHQaF?YSj?XDSibBcSfc;RoDdexnN{fr(F1NNe+R8kbQJ8HOp>=plUtf@r zcL$s!ca4pkx1r_wYzykOD(lb1x72y4Al6Cj?pGF6KZEH!KLY148Z6o80lnd>Q^Lpe z#DVNTj1MEmqryfQ=TpG&w92uBpesr7@&lqRA??@KBn+HCd)arbur6t~;E`%+r!pkw zesE{2F-Z-sa@gM`^*z#g-`!v9%1$`#bi>_EUN%B8tb*qUdIAvF_;l{RqNOH5Ej@~X z^C!&=Akaag8OuO{Ca+Z?7%=1#JdJ~_YEaO^Ej+=w)F_6y-v0uD`K`<(eC4IZ+tO$< zI%+Kx1L0jQX=%zrfx@pcRJ%Ksp#z2+d!3%#`^z0)3MO-0ID4+pa$%@sN6Ig1kQybs z`6x1t!d)23zziH{xBzRxcT;}-_@b{?5`8OxOmK!~`EuH(fRlSl1nihKFy-R*`}D&U;UR)z$L>FK@@-?PZ_S)4S(6VBFh=uD*P%nWMPNl-dnr*A(PX4`mkw5%5 zbboTwn3rHC)z8PSM3Zm$>Ng&3y!^$CTam%a*M;AD3uBBTh`|rGTabDrVHAQ7?`_;( zJi5hh<;z&#w?kYxtYWVQGKFNVkzqON1#g*hLl@qyxbLsTgFzq@%%q< zMlL4S1hmKXn24y#Kbqcw>>5}681Sh$0fI@nX>FChaelHAno91pIpZq-&cbQ`JtaEzS zl4Kzro9u`u-)%p}WKvzV|{mHC~RY-pRjsi-8h3Y@K7pQevEV`ghkRt01t?i80`owSp4N zQfB8$5>XStnM)@z9Ve|Q9-Q=HGKANgp=-XG?(q8=QqzvAKV}TMQ&5P-a|RxIjJ?-J0G5Cr##c1;Gy+uzcv(- zZ-cafM8HR5cJ=CiiM~uYc?x!bBYpK^p0{0hz0Az3dS#p@8Jh=auKoCoCnSYdzL<@v z)C(DGXW%X$e^;0wDW)K7HeIf1S6BX*J1d1llL0lteGm2A50Gg%@n)alLvP2~GdhCexS_#~ET9+3&jnWkKRwrxNmA+FLG7X>$4~yE^?c zr>AE+p|yk?yXw1&sW&*XnZ;sHYRn5Ur|kJ#oz>3W6GSKA+DA%(D%b@hE2t}FGqu1K z&v^RIZPf}ZeBZKW(*AiM`!}PuPv6+$ivwr5aG}0jP@xmhHcFWhu6GkM3%kYcKpO9N zv6$AM*gF*@h`gZlUgsz0n=4gsHxejF;(Yacrosl;-6NjwMV~DIj^X9Ak+@4pDE@}K zVi@_N4&B2$dt{l{R14?$q^_of1NY6{J2||!ziu{?NQdishJ49JaP0Z7L_}V2-MCJI z@3CZ8He8CM`c|U{^aX2G0}R_fEgWJ;g@E@C$^WCM!AFJt9;-@>EqpzMnMn&!!8oMT z9BZzX5q8N=UWOuV@!_A0R&1DzGp5c@Ej?{yV6@WGGY+O@gLLA;QoBIKYy5P@8#>R^su_1*{{El%woY(6!2`TzM{I=SkiJ zbUrKk>hDTS>w8|QaRpn&7g%D7!^n4T-2y5T;O?am!ReEp&*nD*Sfd&V;5ADCK|UW+ zCI2|-(7Y<&-q2z@=F?4yfwUVm(J96Uqs>^H_Ey=h#TOi%8fmSBjFK{L9XjgWjQJ0h z{lmhIm%H(W&FrmkijzYvLZH+V#yDu!VIh9v0$kx#&J($X9&Uu% zw{%RH?@uycwBZozH>kAPK4L}%4-7nyV5s@Bjmv-Yd>7-$s{c6l?7d`bR z`{;2#0I{H8Y*KOm0oxpfU%!`{3VnO>pSxIm?QU%*NYB_+rSVvt8Y^%hz2u@i(_dX) zPv>DFLpeu(_<_0As}&&&6RxCK{~ z+5e)7a)wzfPz!GT+>}0hjH+2#^;(4Qa@96l@6HO1$zFSFxR@})m` zxmsEbouR~Lx)y-*Vq))v!LBuQy5Zq z@O^gQ?of6}BVjwe)02pb?4zRe-q9wzuaoJc(a((pA>pM$I|KZ`cW zt+VZX`s^_iL^L5ZtEJAY9`D6(eRDGS(h=>%Vy0~b^IoNxT@Sx+v^6OW?fvY6E*yX{ zEifj@MX=Mv=)g>f4&~dXjb%TKHovSCA5>x-04b6{O2*jJ%+vC5d3QI-b(5zbv)7p)$!YcG2)H?!p9B&w1(}-Nw*jGkQaCpm zT*7((huPT%aq%I>pS$twNg>a+%SW`oS8Ty=XUtgQuYfd<)_*Z`;i6Zs#j``sAG^CE zi$CphyP{-pjmGAe+jqD6WkD?30}4_4IjDEW$bRIej{4+NfvyAa)(hSl-+hGJG4np_`%u}*PNStu%jaTPVmR}8yT(@*}uf9ZkwSe#M#drB-uRvn(BjgWZrWo0+fb zv6qLAc{qR9@y%Pf?tL9yH5_;4ej75^1`;3WdQLuI75lmA3TzSdf7IEi4`PfHE?)9NY6 zLl1ApQ|?|X=JWjPhUr`#^}cIiCp{jqwAye?CNeZ$fURD2S~UBvI`QPMwl;TsE~B5; zJX+sP_DN?)Ahe%Xr<8oZ+;s!XvN*e;TG(_n?5n8jU3R2_U&cr}-t+T`{@UcbR>`;Q z!S&B`L>jAtcyYTVI}=LAO0kpOsvKo@so;0{o{EOd$OZKHGcJ*Q`xlrkRa=zizn*ET zQ*?wG1qg%ThppkaPG!kU-6S^-O(`KO=VguV_DjfMK;C$f$3f2?+gGV`T|K#rHL>`l z#oLPPg2Rl%Qmg0m>CUo&MOkF^dm-ey!UR@KH>B*>eo6#3}BR#r8 z$cGGy;2zW{-)ryMe1od2V-q=>}dde-v#9G?vw9dmx`T^vEyHM%2c5LFs6UverA85^ysli1Ebin`d(fo zW1Iuy5$M89a^pdA2J(AHx9!#O$vrl zAmUKleags(17uvFOkOEpg(DCk@4`(6)y8(XA-tw}^wU<}k%1=8vo z8h+b@Yjm;ybE_O?Mkn@xAUmke^=RL3QP?7*PW`HHT5XHLHUhvqED)baHUogbCKsra z-Me2bJEXM9o1G+wUkd!y(d(F58tz1BYjBIwBWF-T-4Ujfc1%08eMkIFne#uKmvR!W zqFC6P@M)I&M#EV@$ZvMg;%L1w4H&e_k3?G?JYMwI=x;RV%4t~u8!u*uBZU)HG@Z3nSZE$9FW0M6m#QN zQXx%;vn&f~>?rdRh|oD_9dQ@f!9Hrdy5JDC*JnE3UxZ*L3rcF~*%ISx{~CigFY)4I zhTUU-&GgUaRcJeC$f|`q#$>lKW3wSkyd#K7ErAv+O-v^aX<(-`#qcGkq|dcb_BUKz zx@JKOnMdpAPCCk?Gg~l~{yMpPQ&`~?`YFq))62%1Yc~9y1#K6C_ZhB5RC{{#4zwh! z)&V*<#@2FyofrbDQUYB!+9?xrAZ}u(qmSMqa3qy$_tXKl5s2Do00VUkvzVjaDzPO) zW@#y%+>75`e~q67(94V@u_J!KjmIo`TX)1RWU`-Yt+Z|wj|%kF6|gqgjLbwp7UDdy zCOgv7HUNZUO{LshHdvjS?r;-2lIJ=@I?6>~OVf!1n;qUmoOwR8^%>&3Od&|2+(hhQ}Xkz&*U+}?Su(PycS&%BRD!=61BA-X+e zM^0CP#zjXFemelxV1UjvcBjVZ0&&}9&96|~=R zzvTRm-Q@A3Oq92H`>8e6|K(41yOtr=hLh-9g(wg3kdu|*Ff`=Axy2<}rT+pS1yg49 zN*%U}n2U1hSyor(YtPy9L6%V_#eCII+fW@d7`9K`osaE#TZiZsRwWi6Eq0S~l86qR zQ~hGyv~~?r0?S4Qx$B6lmkrO5+4QHml#?CRJq-A}42957c96MB;*DG1(r%2gMO&?S zYOQ#1W57*QIzM3d6#yWr^;lc|G=226V{nUobc*f0yl4c>9*+m`un>f^&OT*{jAIA1 zw}YvKle4z%Iru-^s&B;H+P24<>^5RNCcP%H_)~IfWQJD}9 zmGHF_@XuHJz($t$TBUoRZ!IgWGxX`+hc&xD4=%E8BdD(d0_wuc{yScsk2}=Nixy+- zCVbB_s>|U4N!`yLSJDC+#=+P0|I4TZ9`h7%a3Jj|UzAfUl(>n_}Z0lV;k_K>e88=7~5x?X%*cG3_0*h$~rfepTOhhej;N#VNuvAv~d zIRpALIsl3F4P`vP_HJgszisF9%TbWd!abD0!q0u7{^5k5E2wWFY~f6c8n!OD{$sF! z4mDv1zrd3gujBK4Syw-wxIXe#p68dfR0f-z-3!Vb@HR7@(50ph4^nfz`7Ew%e%5*~ zvwx2UHrrVZ7!vQ6nJe!s7F;9BUy`Abb?x(sdypAuzJtu*Cl?Um^fC6?W7*P_9aJnV z9$kjqTymo^BbvpA&sEYSo-z9bVzXm@8^GbmwqU=37+?WeVIKIZQ_?0ePvv@H=pQZ3=65 zU6V4?y{|nh7i01lZbJsuf-$6RToWfid$Rxw+id@)2w}avaJj@6eCOu_&Hm<9khKry zEj#9C-C0PfDftjw)#ZmY%8%0$sEEUNjsK>337=(HscAWBSm}Sz@aMJv@OWbt$`1x} zc{P-s*?)(Mn7aGyM?6dAx%MJQrl_j65GNB3H-n$O{FE{ zzKxJb?0_Im@>{M!0(CNL{^Og_SJpwUkH0xb=#k};3@{bGNNCKArlWzM+3#Co za@{*|ZWlpTGwIS?RKsQPBmNETrYiKcUvgzs>)eFfJr0_b}>O`Vw;t8NtS@)DCy?{Y!B# za1%!k(;;5!`pUS}Ph;GfY|`c0kkfi^UBJ!!#@mpys9eW#7c+px|2AQ6qWRJx;FnBN=91 zav^vGnT(mNg*=ip1X&rNEY?l)u%}C@x~v?Ol&W zLhW_o&#nDpK37T?^1x^u0zu+ra$^|z3V_0Tqs31_u{h;z-`Hx;3*|5A8(0jM@gHsm->)0ZBYn+PysMh;Mj zqn88wj@ApzJCQt?6 zX90zxsisgehI5_QXKdFSozN_QN9=~y4aD+dkm6}fLI(^vf9%`JtXoRH5lX5b4y`i& z?ivGWXg|o96vF*dDjl~hw91otc-nCwYYJGK6q|NnX*sVy2NY8IT=O43 z>ml($2LBbxyiX~>H}85LLMLqfq_z;Un!w8#`%{}~c|8D)$~(g`Eb*)fu;7W^TwZfyRQ-o zLnH@HK2-EgUqc+H`rB8E)e2bOShRRqD;QH#3V*r*VhWUpMxSwT{`y8uD4}Q1-?U_mXhnmi*GH7`eP6O)(>^8VDnZR{$X8p=WnSu+PnaTE#&DGc2viM-<$jpTS+>i z9oQ|(J3Q#m0|RbOCgQ%yxiFB2S@eIY!ZpBL;k~gQwLVHQ$MV?5104;>d>}%-98Y#F zd(XG6eBa+xnly~r&hRq)n;qE^e=9Cneit+_g8E29fsLS!dlDp11&NFcnbiJGw^?x1 z8||di9M#Suh_nVvW?<|Q73iSCxppN|r1B)7?s2vo7gE9Eo zcfv|^N)yEI^ci|4fiX4K1ie|?HEc4!82W;Y5X8p-YJBdUhEMSQl_=2|9uGlh0nJ*$R)4BgVpww! zX$S2I)hzZcVyd1IIZ(C`-rjPh*jA6fanL0)B=ri^ykyuv&ULh==_0^21rm*3(l7Q)Nf2IPMxcI+|Fjc3sFoliT?R(jrR7{ z*fjO5LXAdPrL{CsoC7n9G?RM)-vOhlv@po*V;!9m*d(oT!1=OM5Va6QZ8z*>eGTXk z5&ADEzY=s~V@uMfoiHFGENWHg2W_+io2@+l3W(Z0B{}c<(!?bP)yM+*Hh|nHE~v7d zfq+!dMY&2b69Fw^`R3oe!Tv21l3)#PNJGxzaMftabn=l{CU{&B6)!0MATf%ZvVQI> z(gy80{f{PeXqpGFH>8^O^bO@SWVXoX2F%>j1tnQs31n)}Fh`x3KGJ>7V^>$@ZK=^! z1$XO|qCNs_85m^EinS9wvv&nj!3Ak&DbHm)-qCGhJue_Ij-JBfEO{RIkCS5IFPOl2 z3NnB!4^5}T*}(T1;FWr$fRZp!o-LIGR28FF(W8+MT_75fBT<6b&-=PDE@~|O|N;5$s#+a|Us%Im920eP{N>KeG zaEBC|o*N=#!Ef;|Yo4QQhYO7~t=r-770BQc%95s3WQLbdH#lyf{)@%9s!`>lGeG_TeJB9%k(0 z;OBSI_wLwVekgd~QpP4ZW33x&O48v%n?hw~$|gDKOCqx`&bdwO5$mi_oj+IRK36?L zblXgXKN1ttIkqQgO>$6)*5$CNO4rXF53=^m>NXi~KFeD*-#Ymt-J>ObdW6X_wb(SzB>HG6!*fpHjnA@(se{P-fC^LF!F87gv9y!A1@iAvQ=NC z+D4i9Z>Y|87tRz6;+kqP9D{S1M=R@s#+$b+&g}_1dQ*J>it&S6d-vGw>nK!g<1z2o z3(@5-ZF+Zv`03G<;VL1mtfFM)1D2J<-+(#ef0WFbx37rGPGwsp`|uG*Tsyu_67B}c zkGk5-`|$ z+EzAKPv*W)6>r(Pt+kSt{q@C}n)jar*1lp09iS`>wGOr2_N}#ZoT2 zSgb6X)nmDh~v4Yv>Bj1g0eLolfrS0Qzs@4*gwREv$lS6j$ z(;z#p$8F9Jq@dRQ(`xs6DVERoXF`kogzbfX!uF-L+cPc@tA!4{(caSF(FA2ET&+s} zqqr@BK~7?YU%_ynf(Jv>Wms4KX5ZlZ+KTKZvxv|rzImVTyW6JzO#DvIa{X0mp*G&p z3>ST(O%^h392kYpHRy}S21J0Z-&wPL8u_lP7V+adO#g2BxZKLz(!e!v%q3XESUvRm z{dX{fLmOigrQ0UlWMGQ85*6dKPZc`v3j&^| z!3};SJ)43Aa|PxepEX>KF?8?r;;u~ZE=wH&5$kjB`6gPqgZLEmc+*WyAYq<^xD?># zC4Ip~;d}#ZVhP?7Np6fF*BVT3XUbs_>rnXvIp&Sn7Wv5oVm_}!8Ul{it96|>ULw3Y zw{C%!l zD|S0*$&x;Nw1o3%Nt=R=(H@)Xm?C`wv|9CBeOnWTn@?Yj*1n$Ro}imEsY-Mld!Meg z*mz!pCFyel94X25!dcyMRUe6&wyTB&p`IbH_b2c~61Ar0b5?KP|^+xwpGc{R$ROILiDCB6xys4y14!^_9xm2VX1qI$gW%?_Q= zj7HsuO6Pkxe{D-ztN&o&iTT{G0abv?Eb>dgx4bd1h5SsRN9#~NQA=$}iy-u;On;@= z%mlqX2lz>;M}uHYbpc`4g}eG_SHYe3gkg!#x`sZ_!Aln2<%ag1Y8wfX85qqu#?!V@ z|AB4&Js-_`ub(~660qhaj)zP>2dJOf?q8}ouj&&JI~GVA|Y= zB@5Gu-o&G~OAmD4R_&WuDVl0|Im%_serp25n35|if7i1sVRod}YXY^wirq2;tS5TG zId1&wTN38%9#nHrelaZ6=S%#ZrM0(8o3mkrdvShhMO2;I-m0PE_sLhzvcDTB@+>Sr z6yjnvkk*^3D96|oT50e8+8Dl!GTva_=wxmFymIfS_rh^q8s#do!!tuKd1vPCwO9fn z$&kiRz6-sy*w(XJBrxHlIecLujh!Ngaez1JmL18X-rl^N=9~@t`d;2^Y26#i{WB}b%thynuwCR$?va47qsPMi zJEqzVmKMJY^ks+G1sU+Yv~1JvyIHU~s?L?kF?iKN@u!Pi=OtL_^2ZY9KY$e*(GFYEv|QQs~ZRK^yX|d+m$X!HOS~Jpx~R zzkr$St~u8p6*4^YP4;Q^k;R3Ow*^N`C*TanDJ1b-?mo`a(k8X5_!7{mvnA~MbSgD6 zF?tH_? zk}i|3v0n7&7W{+~7<}%2^%H1lB2Q|hXQ_$sePQW)dTgfg^Fm)wpqliVlL>QlI*k&1 z;uFJH?!^1241h3ekFdla?P=QC*9M+SA@+Dfk|UDS%DzRUA!o*L;`LNLNYc8Z!DH^% zg<TnY9NF%=PJtTH!ku(ZBqI->;qD zcRDSqd$7|juBp{K$k)`oM7!YizBx;1N`9(n(%vpB9mJkroBFia3O^dZ(I$COee8>j`5J!yt{>;7oHe-ZXL);)OEk+%A!c1`iBmiehg2<& zwaoH`@r&}|o9lj$e+^g(-@LvV6aC|*yIrO1cJH2Pk9paeQ$Ld1HOs{* z!}dgFwVqm?$*=KK!zwH4lAw`oT~KN6q6#29tb8d=Xes0l>zoqruvyL6?L~(|LKcZV zzd>K)TGZBfu8RhD10|C0ar_=t)kHS9piN?X(p?vsQa$ABYR11%ujf!s-|v0E2U=_gEjnM#{~|bMPME}5Re1Q& zd|(Gx<``GHejD49S1LZ%WeLkz(*r%eLiV_3#zkD4-|K$9zyCZu-uL}Juh%)R^E%^s z&auiRel(uz6JSq8_+4(qPz>AM&$*@Cod|3-W~GcGz6Pdz0hS{aswQo88dE;+w$ts3 z@s(*}9%Kh9$!uMfREi$bD29aX-rXvtKc7NJ4Y-x zuBjBAt=N7$RHRhB8g)jaqV4IEx&*1^77>OusKA*FKmYUa9@*tzTkPC}+RN@rk2A|! zMYq>~QUS;*H+X||=o!OGQ;X!xma+94eYTOzfsHkfuU_CT=P5cl`G9EG0dbouCWPL~ z?rBPSRR27ayzZrP05UeOD0m09>m4NP^#H{3um#*4F6bUS6-Ouu$X(i=In{_&rD2il3HqZdOKpx9pQ(~ zg}1-?H0MXvLdiqj-ZH;ijUdOJkY4+I86T^FP&?P23%;XKj4BX$hd!<#R*H2yg2| zrccNUJB3G)y^Y`?D+!XKM8Yl{q@6ySuJ-k*X0><4tm;1+@$eRq6>@<$G_q2$3i$|F zE&#eKivI?&XiaY)N|`PkwuH_N1Tszg_Tz5{fa61>@;%Af zWbzyU7{mIy&i6^JmSuX8t zIpwA*9rKHu9W+jB+4~ba*#!bvJEgPJ&WR8>U35YfR1~d7g{d;QE9(SgCs@XSDiY4< zX#C^&I7VJfV`2VPQn@!9Vs897cd{nykvKmH=jPg>#dnW>roFb(eqy*tUL@somN1+C zuiMVyXKgl2Hz`t?;(fbXWkgnsm8|#E*B156p9W;utaE~o46H0>LoB-=Iv;s)peN#3 zg}3j^t6?)glgwIF0yA5_%)SvgyeM2M|2g6#_t}uAOw-=VNi!TtAOD?wy&rMQvp?5+ zqx+qy*J4#t@27G{YA+u-2IY&V^S*8@RF_V`$_Bc=UZeMUi>1UqCT--^A+xL_SXbm( z4YEE|MsYOwNZOiCb`K4(Q!(3o<6f*U^$#{l$0HBrIBB1?{nchsDffOH{qaN27-_x9 zcb`g5>Jz?KzqP#foIy5s0BEOL_aqvEH}BKe>k24d%?|6HGnLVB*|Lt?=OMnM6TMhF zoF@*9w;znSV%UA>I#yQ^-H5qMLUqIQ9*j^9P3^f^18nZf!@-!tBU4IK^kJ~aX=4}+ znVx4^h}TVcA&%ilu2x$bSGzy}e31{&1&|sEmP`c{=-_Fjf1r+?8pgRL?H<`r{_`-y z6(Fg{;CtPcG#f-JMKm~JI*dUtM|O*@MY^0!z)>>8yu@n)pG3R%^lyQZo(+;SGobT3 zJq5~v2Kr>T>cO%caLzC_Ay3oB!)(u)C9s@zmd5|sdjkgc*5&Mt)dN-g<_PY_EKA-l@Js7LU6`XlyU7={5Cvi8GK&-) zD7*RY;M=&WmZd4fz-*P>ri7%`-2g`+fOFZ9bAp1h=eN<45l&fiT=Y@rJ$HUUWI>J4 zWuJYY^g7&nX~)tcaUr>&UcAe*`<*owxHKG#?ZUGN^!g3$1khWY#SuRvfbVBvGb*y- zWkK!ko|^ug`SIY9T6Jv)ZSZ-@K*kwEo0?fz-f|J%Y;a0VP(cIFaOKY< zY$2Uk+&c+5Tf4N&;3TXX;-+ojvi55MQoJjN7q6UElO$3e7>Zb0rqdUVc3;1#;IQmP zaCrdCUe0vlV5jRO-WP*~zXy5H7?H_*Oni+Uf{}_<+=U-p%?{6V=B=rowRzP$E%M^x zA%?Y8Era;T5YYZY&cp;2?~~!lxWU{;sX6ThmN|fM{Zm8a>g2X(koxpkY)ri91Oa8d z70EI=uy+@TEH{@m(vla_sAWa(aswU$96X3ls&e*4vmT6Y7IU+`Z z44lqVHLAl?>JEWp6i5XF`>;j1qp>gW0&l8v8UBp~!jls@mo~jBwMV9Bz+dwB%;{z3 zZ?@glvc?N_zl$=xvTL`&PNgWQv0j_Z_Ir{t9UpA2U*3irp-3PO$E{oQBW1lMD!}QhPB5wuzx-;t&GS%PUOZzwBtH3S4%hgDS%1v zS;?1NW&i+$;rn|WSplMRFDwP0Xs3GgX&F;o-&fSauF8w16L}<>Fs>M8G{U~Yh9ugv zqnJ@LfcZ~{XDLWtu@*44Xc->OlQd;sE=&P+&8UyGR_!%`H@%m}+Z>YqjG_@|H6%wM zR`y9T2_)v~2m+EMp!iCV=vot&j85k{HSt1-0KmC=Lem6StWvFZ%dKof&Yi5!dzs5yV3U%#z87}cg9W!3Jm~uTGPsdB*yXGx_9=mUoJP){NTn& zWyqxDn!gR)Lnd@T444D~#_DkQYOWZSxqwWcF}ebI;`qUes?{a-z3bc@P^_Dbaf3&A zFi7&e2H`-l9BQdkql0`*=5s4;!eUimFjMV5XwTLjW(lc+KFF5;W&dY9W;OB3Syu}$ zL6uj#c*rtM&u6lr7DwVn%>V3;f87FW&DD3PGR^DdmpxC8PxyS!|2V!oFIMcBii~o2 zkK=4rkFb!8lPfq){A_qt*GjiW03GBXS5vm9FcsUN(Cq}!Sp}fTS z>|!%ZqYPx+_{lK$+4-gSgllZ&&FM{Qm&?K`X-?PW-VYw6Q3PExa}9;TJ%MJ92&POS zKR*W-*YAp19Pl?Hg_>3+v`@bca}cU~e8A^@B~O=le74?P#L`B-F4M+A9E9Fj9+$oYs{=_-$&BL&5d7IwH#zL7EgVwa~ zC|%{U0G6QA%1^+KCUwlCL_*dVjr&A%8*AR>yzN+K22IXXY zcgj&3A&pGWPBaM(KLSHLfnneb+ZX7I4*}}S^rYn2c4u% zba$T;Nkm8zZu$OVDku}M&HQZyZU5QZ+;a4rt)MrvQZ9}S4#YfcZ5?`k8;_>%X=t$p zAPDfkIbj*o=b3lPd^5LId^OI>+BbVQz#oy9&-D*LRaQ<$%WSCt zwuYG14CPGbjl=u86f;FjbyZUrIkF(TY0p0mvlSaRNI+J5-l4i|EdJXI(6gXd(%h!I zhds+rNU_mFdtarFRp72^A$ayQ!S_G9^vA{V9hQRZbHEnvDThC_FCH@XULdjZz5u}0 z?L)s#V|V`0`tC!-%&B{qD6g4k){A(2SfO1|G47` z960;mT2RKnXCQ+ZeQdY>*Zvvss;}lj)@0hV(_D6yY}LFY4{tMI>KCJtFsQKOH!;BjT0Zm8dL8 z!-9_z_>L6X(()DRq0>Kt?=TS6RLUS{C}3ET*~Eu_U$rbPN%dt+Gk~~*mewA>x7;b7flUS;Muqj*7Jz=ZIX|Irr?6D_2=obt;+sXhpjwSileDSY5Y&O-i)ic(T?A zz%~QIMtd_8^qE#TA{S5}$Img~!;H2~WOD}xfr5QeuoCwAc6-;wmzMxXJGG1tUVR}u zZor57pa+5cUU%@}`WtZYx2PH=2VF&Z|0PIsp1U(ssr($22YLe(!xU2w8oicc&~=Mp zq(V}tE9gXyr^SgN9PNP7(;N|uA;Z1`y9dAnYb_kF8c#RCE-+E8f=Vt>u=AEOgk=?e zJ*yFfV8~lqEs#o47bT&9RS?q2O&sw+AYpy2@WSOc*E4jJN;o@9HuYOM~^Hm z#GMwTIM%}c1=HnP@!rJq=R5a3mx*cL_?ABggh-j(N9%YgQ_4Wt$e}sgA4Z{a>h5I) zoRMI;zQA+98r;eXxXQby zYHw=oA#dpd9%Bm$KL0B%{_E<{?=&%L4)82k6+$*jUc;ZeCl&7G@ZsSDwLnEyPwrg+ z;aJ+(08UMeV=NlvJI{atDijePWZT4&kB4SlQKwi4koStk8#3D7Jt5(l-pMgnIeo@P_1y*`(C&ie>8Q=`) zAJ8YhY)@~mO0szG`m5yOFA-OtAW-|)X7viar-s3=d9%PwRZxu^{AH4l(mn(ksxG18 z-!Dk??WzK?L(7Z-C{QcVOVIrcZ>u#2SDIW+P0aP{E^anRxiI-|b(v56J%(lYy5IlkbZgr`<-;lbUSk3(Ng+A?_w*jd^kVkHGx)wPMD(u`AAh^e;mJVF z$gIimr)>0gVWC#ItnZVsQ}($l9->&9c*~gc4k1ywWRq^(?%-)f_gc~w2>S9fY~9y$ z;1!>Lw!K(v(%aH6FAmtZrZKye5uk%1QXRTZX))lvRmg)Xg3M|m6epw~2;rRg7X&=(&TNO5`XAP)sNWqT~op>qg1W~Y?G5fJMvuoHKN3EkRmUivf4tp7>KY6Gz%jv{YB}@dG4T=3%Ny zO>DgDp?C%jCn19n5wSV4Rh8tm2d)2M8Fjpbc>oA5Xmz@q=A)j`aIG!Clo2wI zHI36~5Z$YD<>s-zx-y^ca~sm9K`!@iP)~p*Li(*Q%zk!TYUpj33X6jR_~w zVq4=gdJpt%BaMev-M*`^J{CrMAI!qiFpP+hbu&O~7aPkcw`wRi;TOr1h_d=Q@bp?f zq*c4LMD^{wj=jJ(TZe9G3rF`RWXGC7kWt!!W$=QjToP>XJL z;yv}@(^8&;LUugMdMvX-g|5X_ruqdW%=Q2oGTH690@(9O^4kv;`6FS60u;?ek<#?d z%S9CU^?0ijI|2>KXyi&Jgp?Vn{`x$6h8-X)G4MqOJOHyXwyjo4ETVh>Ulxfj`(g@5 zh!V+OQ8Rc5Q^)U|XlMc?Q?zm;olQotZgQKeH4Vfz5>Ys)Vg=E zoW2N>c7C^;?DCVF@$`{DHLXATbp$1b{TfYk6+x>uJipaMZ_)K8*EIEYh?~(F1?&3) zRHc+(tJ`FwZvUO7QM1k1U#*QXSpkPX*%?LIkY~37dXS@_jk*mxLcGYAw2jkh9W=6Y zANgl(5jCS1F&eRbt-ktiPlP>J+5#_i{P)G5W;^>PECD^F8lW;a#q+|u8q2tyT-!Mt znZu@e;vGQH${BWN#RPm;;prvr*{F{5bGvRJxZKq7f^UWp=sd};w?S$rV$u7*qnUfsS^w_fT zV)NMBVP{B9mk_D5y<%-w()6o#WVRVo|9i_i(XomVq2fs!H7%>TCvEqFio&n6nw0GYfHaDHYhMUyZ7l z_)U2~3@YB#BFDvBcJzh_$^6--I$A`mZgrEdJe45={Qj zf{19qV{PSM;$ePi?woBNA!LQj5_@HWdt7?2e_Chvh6SeCwe~v^o=mO;WwBTnYi~Mn zg=8|rrw|E-!mVcU*sbT+WA|U)~452p0uqe?#trj(-zk>sCkM1|<4UNx}9Iy{Vbd28RKn5232EjWy0 zAHV)N5?oUug{Yj|dnxw5&xC2gS}Z$Mw=lB*!8-V$m0|dnTjcWe(2jOjmnZi9E0VX0 z{?z$^(zyMJBSC(!%nGnfI-rYtewAdCl)bQdb~|ssL|{4iEhssE$!*;KrYvH7-EDH} z!2Nm{0=j$uEm-PGf^wpIgScF{08my&V5z|-Vujp!m>19Fu4<=UEjfhzP%>|D}L@O)4@Jhg;+qS;>qIJY}poD<~}F zwJr^%1w%aC6|1UgoM)JEns%dcj5@L*M0XWJo`743_w<}+ptHmV@+^%_(_HN}ne5(K zH)2B-r_FQr`G%SwF)TI?;AjPmngmz74ideG+$O_b^;y4tU@}bil^J~giP0MxH4998 z-NF$)WHVDk>%wZY{0@tZVq6hd>A?dX$@xoa(9N}xS4#9~?O5aT2QxvfzU*<<%6@Jj z0VmIph~fld3OCdBM41G#sdAHxTOoO=A}KvyM)g@k?^+l6WwMFJ2}3{+`?a`aH$I4? z_jcD>eL1?>QI_j<=<~*|E@77*^LaMaXJ2$o2A~_agI}GuPl2YB8+D=kp9+cNm4#mu z-V)ttOHWEKQh#&#`X*N#n`U5>ATcrrD?jFa2VI{tml+-bvJv_;a{dyW)bTdy72UKI z{4j1Pe(tU*@^NFPF1`da#HeNs&Y+u0a|=Tn&WYQ&)BD8HMqc=e&3C?!X%ld; z=#x^fD_gq>yb$97w1u7%5pL8+($$YY`8u7b!GSKxPO8RUUSZ*6$y#B930EQtC^v8` z$AIRa5u?!@wgq2UK@sgxIJnUu-)Ksn#BN8(;tqhh(qmeb5+CN|2nEcvv5a~8rp%!S z4la|MHwhmh!hK589lD#Z14U-8Hy2U9>f_jBHqQgNMXo!6z~H8X)07CZM4OsLE1?xI zBAgxsc^90}I2W|$@B3EQ9W}vAJ+vcp-;q(~Y#>?z@H~vfAaAYl!!Dr1Y#;%zZ7i&P_GyF^jVB9Ri} zcnvHmM#P#6XTBEO+&UDKrL++bw8r_{s9rWr5BN1mKdjViZ(^1qEDa1s3{r&d`vU#@ zGv(@$Kk+@|9zBF1W$rLwU@;dYxi;oJY&!SvFjH(i1Ucynq^*k1(_Negu*kouy<~Z#H-`goN*|+<-t4 z&pxJ(#N`r0m_j!`t3s<9BP7@6WP>_`sFXssLm? z_}t2xgTL!Tl@ zU&ma7tD4DwZ*RG(tuf(O>2iOTg%BCFJ-Romyf?|Tc!+u;9Gykn zOqsz|;YYS5^}pR}x=wNR-J0}qsE?SzXj1I`JCIh>dX}(#*^43=w{Zzza3mn5EvasE zPAZiI=G>)A2*e}ZyX#UtV zOZi0r)Pecw;%-Ms<84s_eL(qzqzyyQ#crkc|6jN~v2l%CwZdxFvD?YykXA%}M%cSj zmL+qhWN_&nmGe#bohAZ`!MSMt;ZGPFC+)1#T*i6MUT6w|V3)iEW@}xJINX0T3w{JE z3`MHx#ST|ISCa%>uWr24({s4pNTc(V6!IrZOkYP%m7#q9dmwnQ!OWKHG$K*pqhJWQ z3cvQ7aB?43W99Up`#OH01=D-svUKPNjJQE&ClXEk66FjTeqK<0(D@(VaoaV}iVsB% z=nLFzN^WyuTC*gM9O4mHrHtrqqAB5mN4$s%^U5ldU)$2jSElWU)o0C||E@wYJ}VH3@jDAuvS9b|c4FOoPLq*K~1oOJ75HrbKP!iDc zFAfTp*qK2ghG>0*Bgg3{5gSSB_|~b8ip#6-ssCq0N_!Tka$b|DsOYxZX8-ILmNN%I zvO1#Z(~Li4IzOZ+1_oBs10LfdbzS4JgpP70(5`_*jrD8lzO%Nk%*nZcUedbbhB%m} z;6#Mp2WDf{j=v`mp;{6p;XBui+^7ObBjO3>S$)@&_RFCa!iOkIzr$r$qc^rjZ>(c| zsn9K;yteKJ{5_*sadLt(4G@vpJ7jr4?Neg@|Cn7Yn$A(jNshqY`(@N&<}PFR%Lx#o zc*)X}WlWndr75w3@}?pITYU}4|I9n%&ze}F7rie}Sh2SGu$+NjN|N%}c8;MLmP`3Yj*UkgfM6WWzNWt*y+(tWOgJ!atSn=koG6g_ zjY%SL9qy)$hubNqOsXfsunBj+UrNJZEGmD({^(kzyy~JklgM>abu+)f!a_kU@~FF% zZMg&F)er{r?TZXGV|8QaA#&3_85pk`F!sKw>*MZymN`CE8eIpoqIH0>2ab$>n5M4# z3uc?}%zF Date: Tue, 11 Apr 2023 13:28:27 -0300 Subject: [PATCH 04/17] Update build-pdf.yml Signed-off-by: Rafael Sene --- .github/workflows/build-pdf.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index ae261c2..50e2de6 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -52,7 +52,7 @@ jobs: - name: Setup Ruby and Gemfile content uses: ruby/setup-ruby@v1 with: - ruby-version: "2.6" + ruby-version: "3.2.0" bundler-cache: true # Node.js for wavedrom - uses: actions/cache@v3 From d2564b3c1e7a1b26ac946b241895f1416c822069 Mon Sep 17 00:00:00 2001 From: Rafael Sene Date: Mon, 17 Apr 2023 19:12:16 -0300 Subject: [PATCH 05/17] Update the build process to use containers and add some minor improvements Signed-off-by: Rafael Sene --- .github/workflows/build-pdf.yml | 83 ++++++-------------- .github/workflows/create-release.yml | 31 ++++---- Makefile | 28 +++++-- dependencies/README.md | 1 - readme.adoc | 109 ++++++++++++++++----------- 5 files changed, 123 insertions(+), 129 deletions(-) diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index 50e2de6..efc1e6c 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -1,79 +1,42 @@ -# This workflow installs dependencies for PDF generation, generates the PDF, -# and uploads the PDF as an artifact. - -name: Build Document PDF +name: Build RISC-V Doc Spec Template on: + workflow_dispatch: push: branches: - main pull_request: branches: - main - workflow_dispatch: - workflow_call: - outputs: - name: - description: "The base name of the pdf file (without .pdf extensions)" - value: ${{ jobs.build.outputs.name }} - pdf-name: - description: "The name of the pdf file (with .pdf extensions)" - value: ${{ jobs.build.outputs.pdf-name }} jobs: build: - runs-on: ubuntu-22.04 - - env: - NAME: example-spec - APT_PACKAGES_FILE: ${{ github.workspace }}/dependencies/apt_packages.txt - BUNDLE_GEMFILE: ${{ github.workspace }}/dependencies/Gemfile - BUNDLE_BIN: ${{ github.workspace }}/bin - NPM_PACKAGE_FOLDER: ${{ github.workspace }}/dependencies - outputs: - name: ${{ steps.step1.outputs.name }} - pdf-name: ${{ steps.step2.outputs.pdf-name }} + runs-on: ubuntu-latest + steps: - - name: Set outputs.name - id: step1 - run: echo "name=$NAME" >> $GITHUB_OUTPUT - - name: Set outputs.pdf-name - id: step2 - run: echo "pdf-name=$NAME.pdf" >> $GITHUB_OUTPUT + # Checkout the repository - name: Checkout repository uses: actions/checkout@v3 - with: - submodules: 'true' - - name: Install Ubuntu packages + + # Pull the latest RISC-V Docs container image + # https://github.com/riscv/riscv-docs-base-container-image + # https://hub.docker.com/r/riscvintl/riscv-docs-base-container-image + - name: Pull Container run: | - sudo apt-get update - grep -vE '^#' ${APT_PACKAGES_FILE} | xargs sudo apt-get install --yes --no-install-recommends - # Ruby for asciidoctor - - name: Setup Ruby and Gemfile content - uses: ruby/setup-ruby@v1 - with: - ruby-version: "3.2.0" - bundler-cache: true - # Node.js for wavedrom - - uses: actions/cache@v3 - with: - path: ~/.npm - key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} - restore-keys: | - ${{ runner.os }}-node- - - name: Setup Node.js - uses: actions/setup-node@v3 - with: - node-version: '16' - - name: Install Node.js dependencies - run: npm install ${NPM_PACKAGE_FOLDER} - - name: Generate PDF + docker pull riscvintl/riscv-docs-base-container-image:latest + # Build PDF file using the container + - name: Build Files run: | - PATH=${PATH}:${BUNDLE_BIN}:$(npm bin) \ - make - - name: Archive PDF result + docker run --rm -v ${{ github.workspace }}:/build riscvintl/riscv-docs-base-container-image:latest \ + /bin/sh -c 'make' + # Set the short SHA for use in artifact names + - name: Set short SHA + run: echo "SHORT_SHA=$(echo ${GITHUB_SHA::7})" >> $GITHUB_ENV + + # Upload the built PDF file as artifact + - name: Upload Build Artifact uses: actions/upload-artifact@v3 with: - name: ${{ env.NAME }}.pdf - path: ${{ env.NAME }}.pdf + name: spec-sample-${{ env.SHORT_SHA }}.pdf + path: ${{ github.workspace }}/spec-sample.pdf retention-days: 7 diff --git a/.github/workflows/create-release.yml b/.github/workflows/create-release.yml index 014c0e5..90776df 100644 --- a/.github/workflows/create-release.yml +++ b/.github/workflows/create-release.yml @@ -1,8 +1,4 @@ -# This work flow includes source and PDF in Release. It relies on the build-pdf workflow to create the PDF. -# -# NOTE: At this time it only runs manually. - -name: Create Document Release +name: Create Release on: workflow_dispatch: @@ -29,15 +25,16 @@ jobs: runs-on: ubuntu-latest needs: build steps: - - name: Download Artifacts - uses: actions/download-artifact@v3 - with: - name: ${{ needs.build.outputs.pdf-name }} - - name: Create Release - uses: softprops/action-gh-release@v1 - with: - files: ${{ needs.build.outputs.pdf-name }} - tag_name: v${{ github.event.inputs.version }} - name: Release ${{ github.event.inputs.version }} - draft: ${{ github.event.inputs.draft }} - prerelease: ${{ github.event.inputs.prerelease }} + - name: Download Artifacts + uses: actions/download-artifact@v3 + with: + name: ${{ needs.build.outputs.pdf-name }} + - name: Create Release + uses: softprops/action-gh-release@v1 + with: + files: ${{ needs.build.outputs.pdf-name }} + tag_name: v${{ github.event.inputs.version }} + name: Release ${{ github.event.inputs.version }} + draft: ${{ github.event.inputs.draft }} + prerelease: ${{ github.event.inputs.prerelease }} + body: "This release includes the document in PDF format." \ No newline at end of file diff --git a/Makefile b/Makefile index eaff0cd..8de65a5 100644 --- a/Makefile +++ b/Makefile @@ -1,16 +1,32 @@ +# Makefile for RISC-V Doc Template +# +# This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 +# International License. To view a copy of this license, visit +# http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to +# Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. +# +# SPDX-License-Identifier: CC-BY-SA-4.0 +# +# Description: +# +# This Makefile is designed to automate the process of building and packaging +# the Doc Template for RISC-V Extensions. + HEADER_SOURCE := header.adoc -PDF_RESULT := example-spec.pdf +PDF_RESULT := spec-sample.pdf ASCIIDOCTOR_PDF := asciidoctor-pdf OPTIONS := --trace -a compress \ - --attribute=mathematical-format=svg \ - --attribute=pdf-fontsdir=docs-resources/fonts \ - --attribute=pdf-style=docs-resources/themes/riscv-pdf.yml \ + -a mathematical-format=svg \ + -a pdf-fontsdir=docs-resources/fonts \ + -a pdf-style=docs-resources/themes/riscv-pdf.yml \ --failure-level=ERROR REQUIRES := --require=asciidoctor-bibtex \ --require=asciidoctor-diagram \ --require=asciidoctor-mathematical +.PHONY: all build clean + all: build build: @@ -18,4 +34,6 @@ build: $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE) clean: - rm $(PDF_RESULT) \ No newline at end of file + @echo "Cleaning up generated files" + rm -f $(PDF_RESULT) + diff --git a/dependencies/README.md b/dependencies/README.md index 0841ce8..f64a366 100644 --- a/dependencies/README.md +++ b/dependencies/README.md @@ -1,3 +1,2 @@ Dependencies for the build environment for various package managers. Used in `.github/workflows/`. - diff --git a/readme.adoc b/readme.adoc index 15df15c..d66fb5b 100644 --- a/readme.adoc +++ b/readme.adoc @@ -1,70 +1,43 @@ = RISC-V docs-spec-template -This repository is used to prime GitHub repos for the RISC-V organization which will be used -to create specifications. +This repository serves as a template for creating GitHub repositories within the RISC-V organization that are intended for developing specifications. -**If you are reading this in a specification repo, please update the title for this section and -provide your introduction to your repository.** +**If you are reading this in a specification repository, please update the title for this section and provide a relevant introduction to your repository.** -= License +== License This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). See the link:LICENSE[LICENSE] file for details. -= Contributors +== Contributors Contributors to this specification are contained in the link:contributors.adoc[contributors] file. For instructions on how to contribute please see the link:CONTRIBUTING.md[CONTRIBUTING] file. -= Dependencies +== Building the Document -This project is built using AsciiDoctor (Ruby). The repository has been setup to build the PDF on -checkin using GitHub actions. Workflow dependencies are located in the `dependencies` directory. - -For more information on AsciiDoctor, specification guidelines, or building locally, see the -https://github.com/riscv/docs-dev-guide[RISC-V Documentation Developer Guide]. - -= Cloning the project - -This project uses https://git-scm.com/book/en/v2/Git-Tools-Submodules[GitHub Submodules] -to include the https://github.com/riscv/docs-resources[RISC-V docs-resources project] -to achieve a common look and feel. +=== Building on Container -When cloning this repository for the first time, you must either use -`git clone --recurse-submodules` or execute `git submodule init` and `git submodule update` after the clone to populate the docs-resources directory. Failure to clone the submodule, will result -in the PDF build fail with an error message like the following: +To simplify the building process and avoid dealing with configurations and dependencies, you can build this documentation using a base container image, which contains everything you need. Follow these steps: - $ make - asciidoctor-pdf \ - -a toc \ - -a compress \ - -a pdf-style=docs-resources/themes/riscv-pdf.yml \ - -a pdf-fontsdir=docs-resources/fonts \ - --failure-level=ERROR \ - -o profiles.pdf profiles.adoc - asciidoctor: ERROR: could not locate or load the built-in pdf theme `docs-resources/themes/riscv-pdf.yml'; reverting to default theme - No such file or directory - notoserif-regular-subset.ttf not found in docs-resources/fonts - Use --trace for backtrace - make: *** [Makefile:7: profiles.pdf] Error 1 - -= Building the document - -The final specification form of PDF can be generated using the `make` command. - -= Build the document from a container - -To avoid dealing with configurations and dependencies, you can easily build this documentation from within a base container image which contains everything you need. Here are the steps: - -NOTE: https://docs.docker.com/engine/install/[ensure you have Docker installed] +Prerequisite: https://docs.docker.com/engine/install/[ensure you have Docker installed] +1 - Clone the repository ``` $ git clone https://github.com/riscv/docs-dev-guide.git - +$ cd ./docs-dev-guide +``` +2 - Pull the RISC-V documentation base container image: +``` $ docker pull riscvintl/riscv-docs-base-container-image:latest - +``` +3 - Run the container and execute the build: +``` $ docker run -it -v $(pwd)/docs-spec-template:/build riscvintl/riscv-docs-base-container-image:latest /bin/sh -c 'make' - +``` +Output: +``` Building asciidoc asciidoctor-pdf \ --attribute=mathematical-format=svg \ @@ -77,3 +50,47 @@ asciidoctor-pdf \ --out-file=example-spec.pdf \ header.adoc ``` +4 - Clean +``` +docker run -it -v $(pwd):/build riscvintl/riscv-docs-base-container-image:latest /bin/sh -c 'make clean' +``` +=== Buidling on Local Machine + +==== Dependencies + +This project is built using AsciiDoctor (Ruby). The repository has been setup to build the PDF on +checkin using GitHub actions. Workflow dependencies are located in the `dependencies` directory. + +For more information on AsciiDoctor, specification guidelines, or building locally, see the +https://github.com/riscv/docs-dev-guide[RISC-V Documentation Developer Guide]. + +==== Cloning the project + +This project uses https://git-scm.com/book/en/v2/Git-Tools-Submodules[GitHub Submodules] +to include the https://github.com/riscv/docs-resources[RISC-V docs-resources project] +to achieve a common look and feel. + +When cloning this repository for the first time, you must either use +`git clone --recurse-submodules` or execute `git submodule init` and `git submodule update` after the clone to populate the docs-resources directory. Failure to clone the submodule, will result +in the PDF build fail with an error message like the following: + +``` +$ make +asciidoctor-pdf \ +-a toc \ +-a compress \ +-a pdf-style=docs-resources/themes/riscv-pdf.yml \ +-a pdf-fontsdir=docs-resources/fonts \ +--failure-level=ERROR \ +-o profiles.pdf profiles.adoc + +asciidoctor: ERROR: could not locate or load the built-in pdf theme `docs-resources/themes/riscv-pdf.yml'; reverting to default theme +No such file or directory - notoserif-regular-subset.ttf not found in docs-resources/fonts + Use --trace for backtrace + +make: *** [Makefile:7: profiles.pdf] Error 1 +``` + +==== Building the document + +The final specification form of PDF can be generated using the `make` command. From f841ad0309c6e20f024a2fa38539a4b103087170 Mon Sep 17 00:00:00 2001 From: Rafael Sene Date: Wed, 26 Apr 2023 09:15:39 -0300 Subject: [PATCH 06/17] Update build-pdf.yml This change adds a variable that collects the repository name and append it as part of the PDF generated by the build process. Signed-off-by: Rafael Sene --- .github/workflows/build-pdf.yml | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index efc1e6c..8f34559 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -1,4 +1,4 @@ -name: Build RISC-V Doc Spec Template +name: Build Specification on: workflow_dispatch: @@ -29,14 +29,16 @@ jobs: run: | docker run --rm -v ${{ github.workspace }}:/build riscvintl/riscv-docs-base-container-image:latest \ /bin/sh -c 'make' - # Set the short SHA for use in artifact names - - name: Set short SHA - run: echo "SHORT_SHA=$(echo ${GITHUB_SHA::7})" >> $GITHUB_ENV + # Set the short SHA and repo name for use in artifact names + - name: Set short SHA and repo name + run: | + echo "SHORT_SHA=$(echo ${GITHUB_SHA::7})" >> $GITHUB_ENV + echo "REPO_NAME=$(echo ${GITHUB_REPOSITORY##*/})" >> $GITHUB_ENV # Upload the built PDF file as artifact - name: Upload Build Artifact uses: actions/upload-artifact@v3 with: - name: spec-sample-${{ env.SHORT_SHA }}.pdf - path: ${{ github.workspace }}/spec-sample.pdf + name: ${{ env.REPO_NAME }}-${{ env.SHORT_SHA }}.pdf + path: ${{ github.workspace }}/*.pdf retention-days: 7 From da2d9685a35f6f5409facebf14d8646ea5e9b646 Mon Sep 17 00:00:00 2001 From: Rafael Sene Date: Thu, 27 Apr 2023 16:28:32 -0300 Subject: [PATCH 07/17] Update the build workflow --- .github/workflows/build-pdf.yml | 45 ++++++++++++++++++++++------ .github/workflows/create-release.yml | 40 ------------------------- 2 files changed, 36 insertions(+), 49 deletions(-) delete mode 100644 .github/workflows/create-release.yml diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index 8f34559..7cbbb36 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -1,13 +1,21 @@ -name: Build Specification +name: Build Document PDF on: workflow_dispatch: - push: - branches: - - main - pull_request: - branches: - - main + inputs: + release_type: + description: 'Release type (draft or regular)' + required: true + type: string + default: 'regular' + version: + description: 'Release version, e.g. X.Y.Z:' + required: true + type: string + target_branch: + description: 'Target branch to run the workflow on' + required: true + default: 'main' jobs: build: @@ -24,11 +32,14 @@ jobs: - name: Pull Container run: | docker pull riscvintl/riscv-docs-base-container-image:latest + # Build PDF file using the container - name: Build Files + id: build_files run: | docker run --rm -v ${{ github.workspace }}:/build riscvintl/riscv-docs-base-container-image:latest \ /bin/sh -c 'make' + # Set the short SHA and repo name for use in artifact names - name: Set short SHA and repo name run: | @@ -39,6 +50,22 @@ jobs: - name: Upload Build Artifact uses: actions/upload-artifact@v3 with: - name: ${{ env.REPO_NAME }}-${{ env.SHORT_SHA }}.pdf - path: ${{ github.workspace }}/*.pdf + name: ${{ env.REPO_NAME }}-${{ env.SHORT_SHA }} + path: | + ${{ github.workspace }}/*.pdf retention-days: 7 + + - name: Create Release + if: steps.build_files.outcome == 'success' && github.event_name == 'workflow_dispatch' && github.event.inputs.release_type != '' + uses: softprops/action-gh-release@v1 + with: + draft: ${{ github.event.inputs.release_type == 'draft' }} + tag_name: v${{ github.event.inputs.version }} + name: ${{ env.CURRENT_DATE }} + body: | + This release was created by: ${{ github.event.sender.login }} + Release Notes: ${{ github.event.inputs.release_notes }} + files: | + ${{ github.workspace }}/*.pdf + env: + GITHUB_TOKEN: ${{ secrets.GHTOKEN }} diff --git a/.github/workflows/create-release.yml b/.github/workflows/create-release.yml deleted file mode 100644 index 90776df..0000000 --- a/.github/workflows/create-release.yml +++ /dev/null @@ -1,40 +0,0 @@ -name: Create Release - -on: - workflow_dispatch: - inputs: - version: - description: 'Release version, e.g. X.Y.Z:' - required: true - type: string - prerelease: - description: 'Tag as a pre-release?' - required: false - type: boolean - default: true - draft: - description: 'Create release as a draft?' - required: false - type: boolean - default: false - -jobs: - build: - uses: ./.github/workflows/build-pdf.yml - release: - runs-on: ubuntu-latest - needs: build - steps: - - name: Download Artifacts - uses: actions/download-artifact@v3 - with: - name: ${{ needs.build.outputs.pdf-name }} - - name: Create Release - uses: softprops/action-gh-release@v1 - with: - files: ${{ needs.build.outputs.pdf-name }} - tag_name: v${{ github.event.inputs.version }} - name: Release ${{ github.event.inputs.version }} - draft: ${{ github.event.inputs.draft }} - prerelease: ${{ github.event.inputs.prerelease }} - body: "This release includes the document in PDF format." \ No newline at end of file From d3522c225a0e03fb82f9cf02f524937c7dd069a4 Mon Sep 17 00:00:00 2001 From: Rafael Sene Date: Thu, 27 Apr 2023 17:59:40 -0300 Subject: [PATCH 08/17] Update build-pdf.yml Signed-off-by: Rafael Sene --- .github/workflows/build-pdf.yml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index 7cbbb36..e8a8be5 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -16,6 +16,12 @@ on: description: 'Target branch to run the workflow on' required: true default: 'main' + pull_request: + branches: + - '*' + push: + branches: + - '*' jobs: build: @@ -50,7 +56,6 @@ jobs: - name: Upload Build Artifact uses: actions/upload-artifact@v3 with: - name: ${{ env.REPO_NAME }}-${{ env.SHORT_SHA }} path: | ${{ github.workspace }}/*.pdf retention-days: 7 From 81f67f112fa65f8b6422f3f43faa6c597a9a65ff Mon Sep 17 00:00:00 2001 From: Rafael Sene Date: Thu, 27 Apr 2023 18:24:17 -0300 Subject: [PATCH 09/17] Update build-pdf.yml Signed-off-by: Rafael Sene --- .github/workflows/build-pdf.yml | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index e8a8be5..94372fd 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -52,12 +52,21 @@ jobs: echo "SHORT_SHA=$(echo ${GITHUB_SHA::7})" >> $GITHUB_ENV echo "REPO_NAME=$(echo ${GITHUB_REPOSITORY##*/})" >> $GITHUB_ENV - # Upload the built PDF file as artifact - - name: Upload Build Artifact + # Upload the built PDF files as individual artifacts + - name: Upload Build Artifacts + run: | + for file in ${{ github.workspace }}/*.pdf; do + filename=$(basename "$file") + echo "Uploading $filename" + echo "ARTIFACT_NAME=$filename" >> $GITHUB_ENV + echo "ARTIFACT_PATH=$file" >> $GITHUB_ENV + done + + - name: Upload Artifact uses: actions/upload-artifact@v3 with: - path: | - ${{ github.workspace }}/*.pdf + name: ${{ env.ARTIFACT_NAME }} + path: ${{ env.ARTIFACT_PATH }} retention-days: 7 - name: Create Release From 296ec01f634f45d81e3afb22f9beca66b4cc6c96 Mon Sep 17 00:00:00 2001 From: Rafael Sene Date: Tue, 6 Jun 2023 16:41:50 -0300 Subject: [PATCH 10/17] Upgrade the build process * Add the capability to set revision mark * Add the capability to build on container or directly on the host using the Makefile * Fix the document layout to show all 8 pages * Enable CI for all PRs and Commits Signed-off-by: Rafael Sene --- .github/workflows/build-pdf.yml | 92 ++++++++++------------ Makefile | 38 +++++++-- header.adoc | 20 +++-- readme.adoc | 131 ++++++++++++-------------------- 4 files changed, 128 insertions(+), 153 deletions(-) diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index 94372fd..1939dee 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -1,85 +1,73 @@ -name: Build Document PDF +name: Create Specification Document +# The workflow is triggered by pull request, push to main, and manual dispatch. on: workflow_dispatch: inputs: - release_type: - description: 'Release type (draft or regular)' - required: true - type: string - default: 'regular' version: description: 'Release version, e.g. X.Y.Z:' required: true type: string - target_branch: - description: 'Target branch to run the workflow on' - required: true - default: 'main' + revision_mark: + description: 'Set revision mark as Draft or Release:' + required: true + type: string + default: 'Draft' + prerelease: + description: 'Tag as a pre-release?' + required: false + type: boolean + default: true + draft: + description: 'Create release as a draft?' + required: false + type: boolean + default: false pull_request: - branches: - - '*' push: branches: - - '*' + - main jobs: build: runs-on: ubuntu-latest steps: - # Checkout the repository + # Step 1: Checkout the repository - name: Checkout repository uses: actions/checkout@v3 + with: + submodules: 'recursive' - # Pull the latest RISC-V Docs container image - # https://github.com/riscv/riscv-docs-base-container-image - # https://hub.docker.com/r/riscvintl/riscv-docs-base-container-image + # Step 2: Pull the latest RISC-V Docs container image - name: Pull Container - run: | - docker pull riscvintl/riscv-docs-base-container-image:latest + run: docker pull riscvintl/riscv-docs-base-container-image:latest - # Build PDF file using the container + # Step 3: Build Files - name: Build Files - id: build_files - run: | - docker run --rm -v ${{ github.workspace }}:/build riscvintl/riscv-docs-base-container-image:latest \ - /bin/sh -c 'make' - - # Set the short SHA and repo name for use in artifact names - - name: Set short SHA and repo name - run: | - echo "SHORT_SHA=$(echo ${GITHUB_SHA::7})" >> $GITHUB_ENV - echo "REPO_NAME=$(echo ${GITHUB_REPOSITORY##*/})" >> $GITHUB_ENV + run: make + env: + VERSION: v${{ github.event.inputs.version }} + REVMARK: ${{ github.event.inputs.revision_mark }} - # Upload the built PDF files as individual artifacts + # Step 4: Upload the built PDF files as a single artifact - name: Upload Build Artifacts - run: | - for file in ${{ github.workspace }}/*.pdf; do - filename=$(basename "$file") - echo "Uploading $filename" - echo "ARTIFACT_NAME=$filename" >> $GITHUB_ENV - echo "ARTIFACT_PATH=$file" >> $GITHUB_ENV - done - - - name: Upload Artifact uses: actions/upload-artifact@v3 with: - name: ${{ env.ARTIFACT_NAME }} - path: ${{ env.ARTIFACT_PATH }} - retention-days: 7 - + name: Build Artifacts + path: ${{ github.workspace }}/*.pdf + retention-days: 30 + + # Create Release - name: Create Release - if: steps.build_files.outcome == 'success' && github.event_name == 'workflow_dispatch' && github.event.inputs.release_type != '' uses: softprops/action-gh-release@v1 with: - draft: ${{ github.event.inputs.release_type == 'draft' }} + files: ${{ github.workspace }}/*.pdf tag_name: v${{ github.event.inputs.version }} - name: ${{ env.CURRENT_DATE }} - body: | - This release was created by: ${{ github.event.sender.login }} - Release Notes: ${{ github.event.inputs.release_notes }} - files: | - ${{ github.workspace }}/*.pdf + name: Release ${{ github.event.inputs.version }} + draft: ${{ github.event.inputs.draft }} + prerelease: ${{ github.event.inputs.prerelease }} env: GITHUB_TOKEN: ${{ secrets.GHTOKEN }} + if: github.event_name == 'workflow_dispatch' + # This condition ensures this step only runs for workflow_dispatch events. diff --git a/Makefile b/Makefile index 8de65a5..ad48dfe 100644 --- a/Makefile +++ b/Makefile @@ -12,12 +12,22 @@ # This Makefile is designed to automate the process of building and packaging # the Doc Template for RISC-V Extensions. +DATE ?= $(shell date +%Y-%m-%d) +VERSION ?= v0.0.0 +REVMARK ?= Draft +DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \ +riscvintl/riscv-docs-base-container-image:latest + HEADER_SOURCE := header.adoc PDF_RESULT := spec-sample.pdf ASCIIDOCTOR_PDF := asciidoctor-pdf -OPTIONS := --trace -a compress \ +OPTIONS := --trace \ + -a compress \ -a mathematical-format=svg \ + -a revnumber=${VERSION} \ + -a revremark=${REVMARK} \ + -a revdate=${DATE} \ -a pdf-fontsdir=docs-resources/fonts \ -a pdf-style=docs-resources/themes/riscv-pdf.yml \ --failure-level=ERROR @@ -25,15 +35,31 @@ REQUIRES := --require=asciidoctor-bibtex \ --require=asciidoctor-diagram \ --require=asciidoctor-mathematical -.PHONY: all build clean +.PHONY: all build clean build-container build-no-container all: build -build: - @echo "Building asciidoc" +build: + @echo "Checking if Docker is available..." + @if command -v docker &> /dev/null ; then \ + echo "Docker is available, building inside Docker container..."; \ + $(MAKE) build-container; \ + else \ + echo "Docker is not available, building without Docker..."; \ + $(MAKE) build-no-container; \ + fi + +build-container: + @echo "Starting build inside Docker container..." + $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)" + @echo "Build completed successfully inside Docker container." + +build-no-container: + @echo "Starting build..." $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE) + @echo "Build completed successfully." clean: - @echo "Cleaning up generated files" + @echo "Cleaning up generated files..." rm -f $(PDF_RESULT) - + @echo "Cleanup completed." \ No newline at end of file diff --git a/header.adoc b/header.adoc index 9c80801..5fb1282 100644 --- a/header.adoc +++ b/header.adoc @@ -1,25 +1,24 @@ = RISC-V Example Specification Document (Zexmpl) -Author 1; Author 2; RISC-V Task Group - -[[header]] +Authors: Author 1, Author 2 +:docgroup: RISC-V Task Group :description: RISC-V Example Specification Document (Zexmpl) :company: RISC-V.org :revdate: 1/2023 :revnumber: 1.0 -:revremark: This document is in development. Assume everything can change. See http://riscv.org/spec-state for details. +:revremark: This document is under development. Expect potential changes. Visit http://riscv.org/spec-state for further details. +:revinfo: :url-riscv: http://riscv.org :doctype: book :preface-title: Preamble :colophon: :appendix-caption: Appendix -:imagesdir: images +:imagesdir: docs-resources/images :title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center] // Settings: :experimental: :reproducible: -// needs to be changed? bug discussion started //:WaveDromEditorApp: app/wavedrom-editor.app -:imagesoutdir: images +:imagesoutdir: docs-resources/images :bibtex-file: example.bib :bibtex-order: alphabetical :bibtex-style: apa @@ -39,13 +38,12 @@ endif::[] :footnote: :xrefstyle: short -// Preamble [WARNING] .This document is in the link:http://riscv.org/spec-state[Development state] ==== -Assume everything can change. This draft specification will change before -being accepted as standard, so implementations made to this draft -specification will likely not conform to the future standard. +Expect potential changes. This draft specification is likely to evolve before +it is accepted as a standard. Implementations based on this draft +may not conform to the future standard. ==== [preface] diff --git a/readme.adoc b/readme.adoc index d66fb5b..a88fe34 100644 --- a/readme.adoc +++ b/readme.adoc @@ -1,96 +1,59 @@ -= RISC-V docs-spec-template += RISC-V Specification Template -This repository serves as a template for creating GitHub repositories within the RISC-V organization that are intended for developing specifications. +This repository serves as a blueprint for creating GitHub repositories within the RISC-V organization for the purpose of developing specifications. The template aims to facilitate and standardize the process of specification development. -**If you are reading this in a specification repository, please update the title for this section and provide a relevant introduction to your repository.** +NOTE: If you are viewing this in a specification repository, kindly update the title for this section and provide an introduction relevant to your repository. == License -This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). -See the link:LICENSE[LICENSE] file for details. +This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). For details, see the link:LICENSE[LICENSE] file. == Contributors -Contributors to this specification are contained in the link:contributors.adoc[contributors] file. +The list of contributors to this specification is maintained in the link:contributors.adoc[contributors] file. -For instructions on how to contribute please see the link:CONTRIBUTING.md[CONTRIBUTING] file. +For guidelines on how to contribute, refer to the link:CONTRIBUTING.md[CONTRIBUTING] file. == Building the Document -=== Building on Container - -To simplify the building process and avoid dealing with configurations and dependencies, you can build this documentation using a base container image, which contains everything you need. Follow these steps: - -Prerequisite: https://docs.docker.com/engine/install/[ensure you have Docker installed] - -1 - Clone the repository -``` -$ git clone https://github.com/riscv/docs-dev-guide.git -$ cd ./docs-dev-guide -``` -2 - Pull the RISC-V documentation base container image: -``` -$ docker pull riscvintl/riscv-docs-base-container-image:latest -``` -3 - Run the container and execute the build: -``` -$ docker run -it -v $(pwd)/docs-spec-template:/build riscvintl/riscv-docs-base-container-image:latest /bin/sh -c 'make' -``` -Output: -``` -Building asciidoc -asciidoctor-pdf \ - --attribute=mathematical-format=svg \ - --attribute=pdf-fontsdir=docs-resources/fonts \ - --attribute=pdf-style=docs-resources/themes/riscv-pdf.yml \ - --failure-level=ERROR \ - --require=asciidoctor-bibtex \ - --require=asciidoctor-diagram \ - --require=asciidoctor-mathematical \ - --out-file=example-spec.pdf \ - header.adoc -``` -4 - Clean -``` -docker run -it -v $(pwd):/build riscvintl/riscv-docs-base-container-image:latest /bin/sh -c 'make clean' -``` -=== Buidling on Local Machine - -==== Dependencies - -This project is built using AsciiDoctor (Ruby). The repository has been setup to build the PDF on -checkin using GitHub actions. Workflow dependencies are located in the `dependencies` directory. - -For more information on AsciiDoctor, specification guidelines, or building locally, see the -https://github.com/riscv/docs-dev-guide[RISC-V Documentation Developer Guide]. - -==== Cloning the project - -This project uses https://git-scm.com/book/en/v2/Git-Tools-Submodules[GitHub Submodules] -to include the https://github.com/riscv/docs-resources[RISC-V docs-resources project] -to achieve a common look and feel. - -When cloning this repository for the first time, you must either use -`git clone --recurse-submodules` or execute `git submodule init` and `git submodule update` after the clone to populate the docs-resources directory. Failure to clone the submodule, will result -in the PDF build fail with an error message like the following: - -``` -$ make -asciidoctor-pdf \ --a toc \ --a compress \ --a pdf-style=docs-resources/themes/riscv-pdf.yml \ --a pdf-fontsdir=docs-resources/fonts \ ---failure-level=ERROR \ --o profiles.pdf profiles.adoc - -asciidoctor: ERROR: could not locate or load the built-in pdf theme `docs-resources/themes/riscv-pdf.yml'; reverting to default theme -No such file or directory - notoserif-regular-subset.ttf not found in docs-resources/fonts - Use --trace for backtrace - -make: *** [Makefile:7: profiles.pdf] Error 1 -``` - -==== Building the document - -The final specification form of PDF can be generated using the `make` command. +=== Prerequisites + +To build the document, you'll need the following tools installed on your system: + +* Make +* asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram and asciidoctor-mathematical +* Docker + +=== Clonning the Repository + +`git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git` + +=== Building the Documentation + +To start the build process, run `cd ./docs-spec-template && make build`. + +The Makefile script will check the availability of Docker on your system: + +* If Docker is available, the documentation will be built inside a Docker container using the image riscvintl/riscv-docs-base-container-image:latest. This ensures a consistent build environment across different systems. +* If Docker is not available, the documentation will be built directly on your system using the installed tools. + +The documentation is generated from the AsciiDoctor source files in your project. The primary source file is specified by the `HEADER_SOURCE` variable in the Makefile. + +The build process utilizes several options, including theming and font settings, and generates a PDF document as output. + +=== Cleaning up + +To clean up the generated files, run `make clean`. This will remove the generated PDF file. + +== Versioning + +The `VERSION` variable is used to specify the revision number for the generated documentation. The default revision number is "v0.0.0". + +== Customization + +You can customize the build process by modifying the following variables in the Makefile: + +* `DATE`: Specifies the revision date for the generated documentation. The default value is the current date. +* `REVMARK`: Specifies the revision remark for the generated documentation. The default value is "Draft". +* `PDF_RESULT`: Specifies the name of the output PDF file. +* `DOCKER_RUN`: Defines the Docker run command used when Docker is available. \ No newline at end of file From e80e9f5bb4602f872c5d74d7c2c43cec50e1b18a Mon Sep 17 00:00:00 2001 From: Bill Traynor Date: Wed, 28 Jun 2023 10:57:58 -0400 Subject: [PATCH 11/17] Fixed a typo Cloning was spelled wrong. Signed-off-by: Bill Traynor --- readme.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/readme.adoc b/readme.adoc index a88fe34..4156651 100644 --- a/readme.adoc +++ b/readme.adoc @@ -24,7 +24,7 @@ To build the document, you'll need the following tools installed on your system: * asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram and asciidoctor-mathematical * Docker -=== Clonning the Repository +=== Cloning the Repository `git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git` @@ -56,4 +56,4 @@ You can customize the build process by modifying the following variables in the * `DATE`: Specifies the revision date for the generated documentation. The default value is the current date. * `REVMARK`: Specifies the revision remark for the generated documentation. The default value is "Draft". * `PDF_RESULT`: Specifies the name of the output PDF file. -* `DOCKER_RUN`: Defines the Docker run command used when Docker is available. \ No newline at end of file +* `DOCKER_RUN`: Defines the Docker run command used when Docker is available. From 88ff3f93fe5d8fd2ca50d3f20692e0776b81819f Mon Sep 17 00:00:00 2001 From: Rafael Sene Date: Thu, 29 Jun 2023 17:55:48 -0300 Subject: [PATCH 12/17] Update build-pdf.yml Add an extra string for setting the revision mark to Stable. Signed-off-by: Rafael Sene --- .github/workflows/build-pdf.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index 1939dee..b7be4dd 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -9,7 +9,7 @@ on: required: true type: string revision_mark: - description: 'Set revision mark as Draft or Release:' + description: 'Set revision mark as Draft, Release or Stable:' required: true type: string default: 'Draft' From 72fba362738ed61bd784da3f749ef9fdebf20ff1 Mon Sep 17 00:00:00 2001 From: Rafael Sene Date: Thu, 29 Jun 2023 18:37:12 -0300 Subject: [PATCH 13/17] Update readme.adoc Signed-off-by: Rafael Sene --- readme.adoc | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/readme.adoc b/readme.adoc index 4156651..d036556 100644 --- a/readme.adoc +++ b/readme.adoc @@ -28,6 +28,26 @@ To build the document, you'll need the following tools installed on your system: `git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git` +=== Versioning, Customization and Makefile Variables + +This section provides an overview of the environment variables used in our Makefile. These variables include DATE, VERSION, and REVMARK. + +* `DATE`: Represents the current date. The default value is generated using the date command on Unix-based systems, formatted as "YYYY-MM-DD". +* `VERSION`: Represents the version of the specification being built. By default, this is set to 'v0.0.0'. You can change this to a different value, like 'v1.0.0', 'v1.1.0', etc., based on the current version of your specification. +* `REVMARK`: This represents a revision marker for the project. Its default value is 'Draft'. You may want to change this to something like 'Release' or 'Stable'. +* `PDF_RESULT`: Specifies the name of the output PDF file. +* `DOCKER_RUN`: Defines the Docker run command used when Docker is available. + +==== Setting Environment Variables + +These variables can be overridden by setting environment variables on your system. Here's how you can do it in Linux and MacOS: + +```bash +export VERSION=v1.2.3 +export REVMARK=Release +export PDF_RESULT=spec.pdf +``` + === Building the Documentation To start the build process, run `cd ./docs-spec-template && make build`. @@ -44,16 +64,3 @@ The build process utilizes several options, including theming and font settings, === Cleaning up To clean up the generated files, run `make clean`. This will remove the generated PDF file. - -== Versioning - -The `VERSION` variable is used to specify the revision number for the generated documentation. The default revision number is "v0.0.0". - -== Customization - -You can customize the build process by modifying the following variables in the Makefile: - -* `DATE`: Specifies the revision date for the generated documentation. The default value is the current date. -* `REVMARK`: Specifies the revision remark for the generated documentation. The default value is "Draft". -* `PDF_RESULT`: Specifies the name of the output PDF file. -* `DOCKER_RUN`: Defines the Docker run command used when Docker is available. From deebd2c6fa0f54fc2d4a710f8432b14b958e0fdd Mon Sep 17 00:00:00 2001 From: Rafael Sene Date: Thu, 29 Jun 2023 20:03:55 -0300 Subject: [PATCH 14/17] Update readme.adoc Add versioning strategy explanation Signed-off-by: Rafael Sene --- readme.adoc | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/readme.adoc b/readme.adoc index d036556..dbc4538 100644 --- a/readme.adoc +++ b/readme.adoc @@ -38,6 +38,50 @@ This section provides an overview of the environment variables used in our Makef * `PDF_RESULT`: Specifies the name of the output PDF file. * `DOCKER_RUN`: Defines the Docker run command used when Docker is available. +==== Versioning Strategy + +In a nutshell, the versioning strategy is as follows: + +```bash +[Start] + | + V +1.0.0-draft[#] --> (Revisions) --> 1.0.0-draft[#] (last draft) + | + V +1.0.0-rc[#] --> (Revisions) --> 1.0.0-rc[#] (last release candidate) + | + V +[Approval] + | + V +1.0.0 (Approved/Ratified) + | + V +(Minor changes, Fixes, Compatible extensions) --> 1.1.0 + | + V +(Corrections, Editorial changes) --> 1.1.1 + | + V +(Incompatible changes, Major new features) --> 2.0.0 +``` + +link:https://docs.google.com/document/d/1ZO3clTdgbm-t6r8GMDQ7CypWl68_3ZeYuHl4e-cS280/edit[RISC-V International has a policy for versioning] +. The purpose of this policy is to ensure consistency and clarity in the versioning of RISC-V artifacts, which can be comprehended by both the RISC-V community and external parties. This policy adheres to Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH). + +The first ratified version of any artifact is expected to be 1.0.0. The policy outlines specific versioning conventions for different stages of specification development: 1.0.0-draft1 for drafts, 1.0.0-rc1 for release candidates, and 1.0.0 for approved and ratified specifications. Furthermore, the use of build-date metadata is encouraged for non-release versions. + +The MAJOR.MINOR.PATCH paradigm is explained as: PATCH for corrections or editorial changes, MINOR for fixes and compatible extensions with limited new functionality, and MAJOR for incompatible changes or significant new features. The policy is effective immediately upon approval. + +Examples: + +* Specification Development - Suppose a new RISC-V specification is being developed. Its version might start as 1.0.0-draft1 for the first draft, then proceed to 1.0.0-rc1 when it reaches the release candidate stage (1.0.0-rc2, 1.0.0-rc3, etc...), and finally settle at 1.0.0 when it's approved and ratified. + +* Update Types - If the ratified specification undergoes a minor update, incorporating fixes or compatible extensions with limited new functionality, it would change to 1.1.0. If there are only corrections or editorial modifications, the version would move to 1.0.1. For incompatible changes or major new features, the version would leap to 2.0.0. + +* Metadata Tagging - Non-release versions of the specification can be tagged with the build date. For example, if a draft version is prepared on June 29, 2023, it could be tagged as 1.0.0-draft1+20230629. + ==== Setting Environment Variables These variables can be overridden by setting environment variables on your system. Here's how you can do it in Linux and MacOS: From 26fbafb26837e3e22ca4d7dbafdcc1408f668be7 Mon Sep 17 00:00:00 2001 From: Tsukasa OI Date: Fri, 8 Sep 2023 06:41:29 +0000 Subject: [PATCH 15/17] Detect Docker robustly "&> /dev/null" works as a redirection from stdout/stderr to /dev/null in Bash but not in POSIX shell (considered as an asynchronous execution and the result of the "command" command cannot be retrieved). As a result, it always assumes that Docker always exists. This commit makes the redirection robust and portable (makes it possible to detect "no Docker" condition correctly). Signed-off-by: Tsukasa OI --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index ad48dfe..2e220f1 100644 --- a/Makefile +++ b/Makefile @@ -41,7 +41,7 @@ all: build build: @echo "Checking if Docker is available..." - @if command -v docker &> /dev/null ; then \ + @if command -v docker >/dev/null 2>&1 ; then \ echo "Docker is available, building inside Docker container..."; \ $(MAKE) build-container; \ else \ @@ -62,4 +62,4 @@ build-no-container: clean: @echo "Cleaning up generated files..." rm -f $(PDF_RESULT) - @echo "Cleanup completed." \ No newline at end of file + @echo "Cleanup completed." From b20864dd21802241ab4d7d4a6efcfa60ea49ed1e Mon Sep 17 00:00:00 2001 From: Jeff Scheel Date: Fri, 20 Oct 2023 14:25:47 -0400 Subject: [PATCH 16/17] Update copyright year to 2023. Signed-off-by: Jeff Scheel --- header.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/header.adoc b/header.adoc index 5fb1282..662789d 100644 --- a/header.adoc +++ b/header.adoc @@ -53,7 +53,7 @@ Attribution 4.0 International License (CC-BY 4.0). The full license text is available at https://creativecommons.org/licenses/by/4.0/. -Copyright 2022 by RISC-V International. +Copyright 2023 by RISC-V International. [preface] include::contributors.adoc[] @@ -63,4 +63,4 @@ include::chapter2.adoc[] // The index must precede the bibliography include::index.adoc[] -include::bibliography.adoc[] \ No newline at end of file +include::bibliography.adoc[] From 12967e04fdd4c45e16d92e4af5ce81b3fea9313b Mon Sep 17 00:00:00 2001 From: Henry Hsieh Date: Sat, 9 Dec 2023 14:41:55 +0800 Subject: [PATCH 17/17] Fix asciidoctor-pdf theme attribute Signed-off-by: Henry Hsieh --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 2e220f1..a46d659 100644 --- a/Makefile +++ b/Makefile @@ -29,7 +29,7 @@ OPTIONS := --trace \ -a revremark=${REVMARK} \ -a revdate=${DATE} \ -a pdf-fontsdir=docs-resources/fonts \ - -a pdf-style=docs-resources/themes/riscv-pdf.yml \ + -a pdf-theme=docs-resources/themes/riscv-pdf.yml \ --failure-level=ERROR REQUIRES := --require=asciidoctor-bibtex \ --require=asciidoctor-diagram \