Installation Layout and Notes

[dralabeing]

These suggestions relate to a cleaner layout that is hierarchical and logically organized such that it reflects the order of activity a user is likely to perform, default modes, exceptions - in that order. System requirements and packages required is missing.

Don't use step numbers in headings like step 1a, 1b etc. These are not steps but different cases. The layout should be self explanatory. e.g start with the most common install scenario, then add in other cases. Ensure that any reference to a topic like docker is first explained before reference. This is not the case currently Organize all Installation sections under a top-level heading in the order of priority. Since there are also build instructions the section title should reflect that as well.

Building and Installation of OpenLane -> Title Basic System Requirements -> Explain packages, prerequisites here PDK Installation Default -> Using Volare etc Manual Setting up and Building OpenLane -> Default installation explanation (Again, not steps please) Building using Docker -> This is the default recommended way, then it should be upfront List each case separately- each section should be self contained without having to refer to a previous step Ubuntu (don't put version nos in heading, it should be in the text description) MacOS

Building from a Dockerless Installation Validating the Installation Updating OpenLane Updating to latest/head Pulling in a specific image

Debugging Installation Errors List out what are common problems and how to handle each case

[armleo]

These suggestions relate to a cleaner layout that is hierarchical and logically organized such that it reflects the order of activity a user is likely to perform, default modes, exceptions - in that order. System requirements and packages required is missing.

Will be done later. Right now ordered accordingly.

Don't use step numbers in headings like step 1a, 1b etc. These are not steps but different cases. The layout should be self explanatory. e.g start with the most common install scenario, then add in other cases.

Ensure that any reference to a topic like docker is first explained before reference. This is not the case currently

True! Added a section about this

Organize all Installation sections under a top-level heading in the order of priority. Since there are also build instructions the section title should reflect that as well.

Done. Please let me know if this is not what you wanted.

[dralabeing]

This is specifically for: https://armleo-openlane.readthedocs.io/en/latest/docs/source/installation.html

The description text needs rework: (verbosity, language, style and specifics). I have modified it as follows to make it simple and convey exactly what is needed. @donn please check what exactly is needed to communicate upfront regarding installation.

OpenLane enables easy to install system pre-requisites (binaries, libraries etc.) for the skywater130 pdk and all required tools to run the flow. Default installation uses Docker images through containers that encapsulate pre-built binaries to simplify the build process.

Writing style, consistency not adhered to in the entire description-Please read this and be consistent- I cango through this separately if you would like.

Please remove Step nos from title - this is not a convention for titles. I have already explained this above. Ignoring Layout makes titles and flow cumbersome and tedious- Again, please think about a logical flow, it doesnt have to be perfect but reasonable. This also relates to the feedback from @kareem.

Where is the PDK part?

Why is there a section assigned to "Containerless/local Installation" if it is not recommended

Add an Recommendations sub-section to advise for clean/default installation. e.g adding containers, using virtual machines etc. right now this is randomly strewn under various headings.

Current Layout: Installation steps Step 1. Installation of System Requirements

Installation of System Requirements is incorrect English. You don't install requirements but packages, libraries etc.

Simple title System Requirements". This is already under Installation so no need to make redundant titles. Installation of requirements on Ubuntu

System Requirements for Ubuntu

Installation of requirements under macOS Requirements in Containerless/Local Installations

Containerless/Local installations

Step 2. Making Docker available without root Step 3. Checking the docker installation Troubleshooting of Step 3. Step 4. Checking the requirements

Checking System Requirements

In order to check installation, you can use following commands: ->This is just an example of writing style change requested Change to: To check installation pre-requisites, type : ( no need to repeat following commands.. it is understood since this is already made clear in the transcript) Step 5. Installing OpenLane This should be Building and Validating OpenLane (since it also validates the installation) Here's another example to improve and be consistent with writing: After the above script downloads OpenLane and installs it, the make test command will test the installation of PDK and OpenLane Suggested change: This installs the latest, stable version of OpenLane and tests the pdk and flow on a simple design (spm). Updating OpenLane

Finally, please ensure the previous review feedback and rework this section for flow order, accuracy, writing style.

[armleo]

OpenLane enables easy to install system pre-requisites (binaries, libraries etc.) for the skywater130 pdk and all required tools to run the flow. Default installation uses Docker images through containers that encapsulate pre-built binaries to simplify the build process.

OpenLane does not enable "easy to install system pre-requisite", the tools are not sky130 PDK specific, the phrasing of sentence is not greate "OpenLane enables ... all required tools to run the flow"?

"Default installation uses Docker images through containers" It's not the default, it is the only one supported. Local installation is there so there is not too much disruption to existing docs.

Writing style, consistency not adhered to in the entire description-Please read this and be consistent- I cango through this separately if you would like.

If you can pinpoint the sections exactly, it will help me. Right now, I read my own documents like 200 times, so I am kind of blind to the issues of the current text, as I do not see them the same way as everybody else sees it.

Please remove Step nos from title - this is not a convention for titles. I have already explained this above.

I think the step numbers are important and should be kept the way they are. Regarding "Step 1a" it's now changed, is this not what you meant?

Where is the PDK part? Why is there a section assigned to "Containerless/local Installation" if it is not recommended

They both need to be removed, I am intentionally not removing them yet. We need to discuss this with Donn probably. The PDK part will be replaced to include the guide to installing specific Standard Cells, this is currently low priority.

In order to check installation, you can use following commands: ->This is just an example of writing style change requested

Change to: To check installation pre-requisites, type : ( no need to repeat following commands.. it is understood since this is already made clear in the transcript)

I am completely lost on what you mean. Could you please clarify? 1. Nobody types anything, they need to copy-paste it, therefore the wording is not good. 2. Your suggestion is too short, it is better if they have more words, otherwise people are not going to read it. 3. "no need to repeat following commands" True, but I could not find a better wording, so decided with this one for now.

Building and Validating OpenLane

Done.

This installs the latest, stable version of OpenLane and tests the pdk and flow on a simple design (spm).

Done.

See: https://armleo-openlane.readthedocs.io/en/merge-window-2/docs/source/installation.html Note, that this changes are in merge-window-2 branch.

[armleo]

Mention that for other PDK installations you need to follow another page.

[armleo]

TITLE: Building and Installation of OpenLane Basic System Requirements [DONE] Installing Docker [DONE] Ubuntu [DONE] MacOS [DONE] Setting up and Building OpenLanen [DONE] Modify this section to mention the other way of installing PDK using Volare [TODO] Validating the Installation [DONE] Updating OpenLane [DONE] Updating to latest/head Suggestion: Add a page regarding pulling the specific version

Discussed and decided to have this as the only requirement for Midterm

[dralabeing]

Installation Add "Overview" for this part. (Ultimately to be review by @donn before merging changes) I have edited this part below for writing style and content. I have made it shorter without any loss of content(This is still not following guidelines! voice, brevity etc...) OpenLane uses Docker images that contain binaries, libraries and packages ready-to-use. All of the flow tools are encapsulated inside the container image

Open source projects typically have to address the challenge of variable user environments- operating systems, virtual machines, cloud based distribution etc. Docker containers alleviate this problem; they are easy to install and encapsulate a large amount of underlying complexity.

OpenLane uses Docker was selected as container engine to simplify the installation process by including pre-built binaries and PDK within the container.

Layout (Please once again follow explained guidelines - I have made edits)

Step 1. Installation of Required Packages (Remember to Capitalize beginning letter of Heading words)

Docker Installation For Ubuntu Required Packages For macOS Containerless/Local Installations (No need to state requirements when we don't support this)

Step 2. Making Docker available without root Step 3. Checking the Docker Installation Troubleshooting Step 3. Step 4. Checking Installation Requirements Step 5. Installing OpenLane (as explained in the review Download does not makes sense- Should be Build, Install or Update) Step 6. Downloading the Docker Image and PDK (Notice consistency in the title if using Checking, Making etc.. should be Downloading) Step 7. Validating the Installation Step 8. Optional: Viewing Test Design Results

Please complete all the content as discussed for final review for midterm consideration Updating OpenLane

[kareefardi]

As -vitor- suggested, I think it looks neater to have output in code blocks. It is difficult to unify all screenshots to similar font size, aspect ratio, etc.

For the layout I have a question for @donn: @dralabeing suggested to add a section to update openlane to a specific version. I am not sure if she still prefers that but I am asking you because I believe that you have a strong opinion about it.

Step 4. python -m venv -h -> python3 -m venv -h Step 6. has a missing space between sky130 and PDK

I think we suggested removing the container-less install section (if not disregard this - I have no strong opinions about it)

[armleo]

done