Update Readme.md to lead you through basic repo workflow #7552

vancem · 2016-10-10T18:53:41Z

The previous README.md associated with the CoreCLR repo very inadequate for developers to successfully make a CoreCLR runtime change. There was simply too much missing information.

This update reorganizes the README.md to fix this. Now the README is a top level document that describes what the repo contains (new), tells you how to build it (existing), WHAT gets built (new), how to use the built artifacts (new), and how to run tests.

It still needs work (information on running tests is pretty incomplete as well as how to debug), but this is a big step forward.

Note that much of the content is new or dramatically changed, so it is probably easier to simply read the end result at https://github.com/vancem/coreclr/tree/DocUpdates.10-7-16, rather than try to read the diffs.

If the changes you want are hard to describe in the comments, you may wish to simply wait until I merge and then do the update yourself. My main goal is to insure that some basic information that I needed to actually do something useful with the Repo is there for others.

…ile tracing (echoing). This make debugging issues with build significantly easier.

vancem · 2016-10-10T18:54:37Z

I will be flattening the commits before I check in, so don't worry about that. It is just that I only want to do it once.

vancem · 2016-10-10T23:51:53Z

@jkotas @stephentoub. I am updating the readme in a fairly major way.

jkotas

@vancem Thanks a lot for writing this down!

jkotas · 2016-10-11T02:48:39Z

Documentation/building/windows-instructions.md


 Visual Studio must be installed. Supported versions:
-
- [Visual Studio 2015](https://www.visualstudio.com/downloads/visual-studio-2015-downloads-vs) (Community, Professional, Enterprise)
+- [Visual Studio 2015](https://www.visualstudio.com/downloads/visual-studio-2015-downloads-vs) (Community, Professional, Enterprise).  The community version is completely free.  

 To debug managed code, ensure you have installed atleast [Visual Studio 2015 Update 3](https://www.visualstudio.com/en-us/news/releasenotes/vs2015-update3-vs).


atleast -> at least

jkotas · 2016-10-11T02:49:01Z

Documentation/building/windows-instructions.md


 The CoreCLR repo build has been validated using CMake 3.5.2. 

 - Install [CMake](http://www.cmake.org/download) for Windows.
- Add it to the PATH environment variable.
+- Add it location (e.g. C:\Program Files (x86)\CMake\bin) to the PATH environment variable.  


it location -> its location

jkotas · 2016-10-11T02:49:31Z

Documentation/building/windows-instructions.md

-PowerShell
----------
-PowerShell is used in the build system. Ensure that it is accessible via the PATH environment variable. Typically this is %SYSTEMROOT%\System32\WindowsPowerShell\v1.0\.
+- Add it location (e.g. AppData\Local\Programs\Python\Python35-32\python.exe) to the PATH environment variable.  


it location -> its location

jkotas · 2016-10-11T02:51:03Z

Documentation/building/windows-instructions.md

-PowerShell
----------
-PowerShell is used in the build system. Ensure that it is accessible via the PATH environment variable. Typically this is %SYSTEMROOT%\System32\WindowsPowerShell\v1.0\.
+- Add it location (e.g. AppData\Local\Programs\Python\Python35-32\python.exe) to the PATH environment variable.  


Do you actually get your installed under AppData? I have not seen it before - I always get mine under c:\python27. Also, the location should not include python.exe - to match the CMake example.

On one machine that was the location, but I just checked another and it is at C:\Python27. I suspect it is the version you install, and maybe I was not admin at the time. Anyway I will change it to c:\Python* (it is just and example...)

jkotas · 2016-10-11T02:52:09Z

Documentation/building/windows-instructions.md


-Clone the CoreCLR and CoreFX repositories (either upstream or a fork).
+- Install [Git For Windws](https://git-for-windows.github.io/)


Windws -> Windows

jkotas · 2016-10-11T03:21:23Z

Documentation/workflow/UsingYourBuild.md

+
+Now Modify the HelloWorld\project.json with the following modifications
+
+1. **Remove** (or comment out) the following line fomr the Microsoft.NETCore.App dependency 


fomr -> form

jkotas · 2016-10-11T03:21:52Z

Documentation/workflow/UsingYourBuild.md

+``` 
+2. Add the following 'runtimes' line at the top level.  The runtime name includes the OS name and the architecture name
+you can find the appropriate name for your OS [here](https://github.com/dotnet/core-docs/blob/master/docs/core/rid-catalog.md).
+This tells the tools exactly which favor of OS and processor architecture you are running on, so it can find the right


favor -> flavor

jkotas · 2016-10-11T03:25:19Z

Documentation/workflow/UsingYourBuild.md

+
+* Coreclr.dll - Most modifications (with the exception of the JIT compiler and tools) that are C++ code update
+  this DLL. 
+* System.Private.CoreLib.dll - If you modified C# it will end up here.  


Maybe worth mentioning System.Private.CoreLib.ni.dll

jkotas · 2016-10-11T03:26:37Z

README.md

+.NET Core relies heavily on the [Nuget](https://en.wikipedia.org/wiki/NuGet) package manager
+which is system to package, distribute and version software components.  See [https://www.nuget.org/](https://www.nuget.org/) 
+for more information on Nuget.   For now it is enough to know Nuget is a system that
+bundles components into *.nupkg files (which are ZIP archives) and these packages can be 'published' 


Enclose *.nupkg in backticks

jkotas · 2016-10-11T03:28:16Z

README.md

+ * **Microsoft.NETCore.TestHost** - This contains the corehost.exe program, which is a small wrapper 
+   that uses the .NET Runtime to run IL DLLs passed to it on the command line.
+ * **Microsoft.TargetingPack.Private.CoreCLR** - A set of assemblies that represent the compile time surface 
+   area of class library is implemented by the runtime itself.


is implemented -> implemented

jkotas · 2016-10-11T15:37:38Z

Documentation/building/windows-instructions.md

-Python
---------
-Python is used in the build system. We are currently using python 2.7.9, although
+Python is used in the build system. We are currently using python 2.7.9, althoughw


althoughw -> although

I have fixes this in the next round of updates.

vancem · 2016-10-11T16:09:15Z

I did an update on this branch (see vancem@45a2d73) but for some reason the pull request is not seeming to recognize that is there (during that time I did try to squash the commits and that may have something to do with it). I am going to merge and then insure that the edits got in.

choikwa · 2016-10-21T22:23:36Z

Just a nit, any particular reason for moving build status from README.md to Documentation/workflow/OfficalAndDailyBuilds.md?

vancem · 2016-10-21T22:36:48Z

@choikwa. The rationale is that the readme can't do everything, and the its central purpose is to tell you how to use the repository's contents (that is build and use the build results). The build status does not fit that theme, so it got moved to a secondary page (one click from the first page).

Update README.md to contain much more information about using the repo

…clr#7552) Update README.md to contain much more information about using the repo Commit migrated from dotnet/coreclr@7c2cf60

vancem and others added 15 commits October 7, 2016 13:51

Be consistant about using __echo as the variable that turns on .CMD f…

bf9fc43

…ile tracing (echoing). This make debugging issues with build significantly easier.

Mostly finished updating Readme. Have to finish other Docs.

2f7ab08

Review Feedback. Standardize on _echo name

0cea014

Fleshed out UsingYourBuild.md docs

94b8313

More doc updates

153ce9c

Added contend on running apps (and some on tests)

95234ad

More Doc updates

21664f1

Fix Links

a3f2e9e

Fix more links

df481df

Moving contribution section

f2edaa3

More small changes

0de2278

Minor update

fab616e

Merge remote-tracking branch 'upstream/master'

a92edee

Merged with master

feea170

Remove file accidentally checked in

f44be9c

dnfclas added the cla-already-signed label Oct 10, 2016

jkotas reviewed Oct 11, 2016

View reviewed changes

vancem and others added 3 commits October 11, 2016 08:19

Update from feedback

45a2d73

Update README.md to contain much more information about using the repo

c46ab85

Merge branch 'DocUpdates.10-7-16' of https://github.com/vancem/coreclr

420d989

jkotas reviewed Oct 11, 2016

View reviewed changes

vancem merged commit 7c2cf60 into dotnet:master Oct 11, 2016

vancem deleted the DocUpdates.10-7-16 branch October 11, 2016 16:10

sergign60 pushed a commit to sergign60/coreclr that referenced this pull request Nov 14, 2016

Update Readme.md to lead you through basic repo workflow (dotnet#7552)

4a99c9d

Update README.md to contain much more information about using the repo

karelz added this to the 2.0.0 milestone Aug 28, 2017

jkotas mentioned this pull request Feb 2, 2019

Add build badges to README dotnet/corefx#35043

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update Readme.md to lead you through basic repo workflow #7552

Update Readme.md to lead you through basic repo workflow #7552

vancem commented Oct 10, 2016

vancem commented Oct 10, 2016

vancem commented Oct 10, 2016

jkotas left a comment

jkotas Oct 11, 2016

jkotas Oct 11, 2016

jkotas Oct 11, 2016

jkotas Oct 11, 2016 •

edited

Loading

vancem Oct 11, 2016

jkotas Oct 11, 2016

jkotas Oct 11, 2016

jkotas Oct 11, 2016

jkotas Oct 11, 2016 •

edited

Loading

jkotas Oct 11, 2016

jkotas Oct 11, 2016

jkotas Oct 11, 2016

vancem Oct 11, 2016

vancem commented Oct 11, 2016

choikwa commented Oct 21, 2016

vancem commented Oct 21, 2016


		Clone the CoreCLR and CoreFX repositories (either upstream or a fork).
		- Install [Git For Windws](https://git-for-windows.github.io/)


		Now Modify the HelloWorld\project.json with the following modifications

		1. Remove (or comment out) the following line fomr the Microsoft.NETCore.App dependency

Update Readme.md to lead you through basic repo workflow #7552

Update Readme.md to lead you through basic repo workflow #7552

Conversation

vancem commented Oct 10, 2016

vancem commented Oct 10, 2016

vancem commented Oct 10, 2016

jkotas left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jkotas Oct 11, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jkotas Oct 11, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vancem commented Oct 11, 2016

choikwa commented Oct 21, 2016

vancem commented Oct 21, 2016

jkotas Oct 11, 2016 •

edited

Loading

jkotas Oct 11, 2016 •

edited

Loading