mirror of
https://github.com/Kae7in/perfview
synced 2026-08-09 12:09:44 +00:00
Add docs for contributing
This commit is contained in:
Vance Morrison
@@ -0,0 +1,72 @@
|
||||
|
||||
#Contributing to the PerfView repository.
|
||||
|
||||
First and foremost, we want to thank you for your willingness the help make PerfView better.
|
||||
Here we describe a bunch of rules/advice associated with doing so and you may end up
|
||||
getting frustrated with the process. This guide is our attempt to keep that frustration
|
||||
as low as possible.
|
||||
|
||||
The simple truth is that no all change is good (big surprise), and because of this, we reserve
|
||||
the right to reject any pull request to this repo. We wont do this without rationale, and
|
||||
our rational is simple at its heart is simple
|
||||
|
||||
1. Complexity is bad. Changes that add complexity need more careful deliberation
|
||||
to weigh the good that comes along with it.
|
||||
|
||||
2. Consistency is good. Bugs are basically a kind of inconsistency (the program does
|
||||
not work as a simple understanding would assume), but there are of feature additions
|
||||
that make consistency better, but it is all to easy for new features to NOT be consistent
|
||||
with existing features.
|
||||
|
||||
3. In addition to the benefit of the new behavior, you must also carefully consider
|
||||
cost to any scenario that is being penalized (e.g. make it slower or more complex,
|
||||
change its UI, or take away functionality).
|
||||
|
||||
And our golden rule
|
||||
|
||||
* **When in doubt, ask us by posting an issue or suggestion**
|
||||
|
||||
The key here is that from your point of view the new feature you are adding looks like unalloyed
|
||||
good. But it it very likely increases complexity (point 1) may affect consistency (point 2)
|
||||
and may make other scenarios slower (e.g. startup, etc). As the keepers of this repo we
|
||||
have the responsibility to weigh these other factors, and we may decide that the bad outweighs
|
||||
the good.
|
||||
|
||||
A rejected pull request is a failure for repo as a whole because it means that multiple people
|
||||
spent time on things that ultimately did not benefit the repo. We want to avoid that. There
|
||||
is a simple heuristic that help
|
||||
|
||||
* ** The bigger the change, the more 'pre-vetting' you need **
|
||||
|
||||
Thus what we DON'T what you to do is over the course of time build up a rather massive change
|
||||
and then as some point decide to submit it as a pull request. The likelihood of this landing
|
||||
in a good place is next to nil.
|
||||
|
||||
Small bug fixes / features that do not add interesting complexity are easy, just do them and
|
||||
submit the pull request. Bigger bug fixes should be vetted by asking first. Code
|
||||
reorganization is particularly tricky. By (1) and (2) we like this assuming it lowers overall
|
||||
complexity and improves consistency, but it is very disruptive and ideally is done in a series
|
||||
of small steps. Thus planning is needed, and you should talk with us by posting the issue.
|
||||
|
||||
In general all features need pre-vetting. The rule here is simple. Don't do any work unless
|
||||
you
|
||||
|
||||
1. Are willing to throw it away (e.g. it was more effort to get it vetted) OR
|
||||
2. You have vetted it with us by creating an issue.
|
||||
|
||||
Performance improvements are often a point of contention. Improvements that make the code
|
||||
smaller/simpler are great, but often this is not the case. If you are adding complexity as
|
||||
part of your improvement (e.g. adding a cache), again, you have to follow the rule above
|
||||
and get it pre-vetted, or be willing to abandon the change. For performance changes in
|
||||
general we will probably ask you to take measurements to quantify exactly how much improvement
|
||||
there was. There is more work than just modifying the code.
|
||||
|
||||
##Coding Standards
|
||||
|
||||
See [PerfView Coding Standards](STANDARDS.md).
|
||||
|
||||
##Testing and Contributing tests
|
||||
|
||||
TODO NOT DONE.
|
||||
|
||||
|
||||
@@ -1,29 +1,62 @@
|
||||
# PerfView
|
||||
PerfView is a performance-analysis tool that helps isolate CPU- and memory-related performance issues.
|
||||
|
||||
If you are unfamiliar with PerfView, there are [PerfView video tutorials](http://channel9.msdn.com/Series/PerfView-Tutorial). As well as [Vance Morrison's blog](http://blogs.msdn.com/b/vancem/archive/tags/perfview) which also gives overview and getting started information.
|
||||
If you are unfamiliar with PerfView, there are [PerfView video tutorials](http://channel9.msdn.com/Series/PerfView-Tutorial).
|
||||
As well as [Vance Morrison's blog](http://blogs.msdn.com/b/vancem/archive/tags/perfview) which also gives overview and getting
|
||||
started information.
|
||||
|
||||
The PerfView executable is ultimately published at the [PerfView download Site](http://www.microsoft.com/en-us/download/details.aspx?id=28567). It is a standalone executable file (packaged in a ZIP archive). You can be running it in less than a minute!
|
||||
The PerfView executable is ultimately published at the
|
||||
[PerfView download Site](http://www.microsoft.com/en-us/download/details.aspx?id=28567).
|
||||
It is a standalone executable file (packaged in a ZIP archive). You can be running it in less than a minute!
|
||||
|
||||
The PerfView user’s guide is part of the application itself, however you can get the .HTM file for it in the user’s guide in the source code itself at [PerfView/SupportDlls/UsersGuide.htm](src/PerfView/SupportDlls/UsersGuide.htm), however it is a significantly better experience if you simply download PerfView and select the Help -> User's Guide menu item.
|
||||
The PerfView user’s guide is part of the application itself, however you can get the .HTM file for it in
|
||||
the user’s guide in the source code itself at [PerfView/SupportDlls/UsersGuide.htm](src/PerfView/SupportDlls/UsersGuide.htm) or
|
||||
[the raw view](https://raw.githubusercontent.com/Microsoft/perfview/master/src/PerfView/SupportDlls/UsersGuide.htm?token=AIEUlpLp2aAS0_OgCbvDPMOz6U6leXDvks5XHMNFwA%3D%3D)
|
||||
however it is a significantly better experience if you simply download PerfView and select the Help -> User's Guide menu item.
|
||||
|
||||
###How to Build and Debug PerfView
|
||||
PerfView is designed to build in Visual Studio 2013 or later.
|
||||
|
||||
* The solution file is src/PerfView/Perfview.sln. Opening this file in Visual file and selecting the Build -> Build Solution, will build it. It follows standard Visual Studio conventions, and the resulting PerfView.exe file ends up in the src/PerfView/bin/<BuildType>/PerfView.exe You need only deploy this one EXE to use it.
|
||||
* The solution consists of 11 projects, representing support DLLs are the main EXE. To run PerfView in the debugger (F5) **you need to make sure that the 'Startup Project' is set to the 'PerfView' project** so that it launches the main EXE. If the PerfView project is not bold, right click on the PerfView project in the 'Solution Explorer (on right) and select 'Set as Startup Project'. After doing this 'Start Debugging' (F5) should work. (it is annoying that this is not part of the .sln file...).
|
||||
* The solution file is src/PerfView/Perfview.sln. Opening this file in Visual file and selecting the Build -> Build Solution,
|
||||
will build it. It follows standard Visual Studio conventions, and the resulting PerfView.exe file ends up in the
|
||||
src/PerfView/bin/<BuildType>/PerfView.exe You need only deploy this one EXE to use it.
|
||||
|
||||
* The solution consists of 11 projects, representing support DLLs are the main EXE. To run PerfView in the
|
||||
debugger (F5) **you need to make sure that the 'Startup Project' is set to the 'PerfView' project** so that it launches
|
||||
the main EXE. If the PerfView project is not bold, right click on the PerfView project in the 'Solution
|
||||
Explorer (on right) and select 'Set as Startup Project'. After doing this 'Start Debugging' (F5) should work.
|
||||
(it is annoying that this is not part of the .sln file...).
|
||||
|
||||
####Information for build troubleshooting.
|
||||
* One of the unusual things about PerfView is that it incorporates its support DLL into the EXE itself, and these get unpacked on first launch. This means that there are tricky dependencies in the build that are not typical. You will see errors that certain DLLs can't be found if there were build problems earlier in the build. Typically you can fix this simply by doing a normal (non-clean) build, since the missing file will be present from the last compilation. If this does not fix things, see if the DLL being looked for actually exists (if it does, then rebuilding should fix it). It can make sense to go down the project one by one and build them individually to see which one fails 'first'.
|
||||
* Another unusual thing about PerfView is that it includes an extension mechanism complete with samples of using that. This extensions is the 'Global' project (Called that because it is the Global Extension whose commands don't have a 'scope') and needs to refer to PerfView to resolve some of its references. Thus you will get many 'not found' issues in the 'Global' project. These can be ignored until you get every other part of the build working.
|
||||
* One of the unusual things about PerfView is that it incorporates its support DLL into the EXE itself, and these get
|
||||
unpacked on first launch. This means that there are tricky dependencies in the build that are not typical. You will
|
||||
see errors that certain DLLs can't be found if there were build problems earlier in the build. Typically you can fix
|
||||
this simply by doing a normal (non-clean) build, since the missing file will be present from the last compilation.
|
||||
If this does not fix things, see if the DLL being looked for actually exists (if it does, then rebuilding should fix it).
|
||||
It can make sense to go down the project one by one and build them individually to see which one fails 'first'.
|
||||
|
||||
* Another unusual thing about PerfView is that it includes an extension mechanism complete with samples of using that.
|
||||
This extensions is the 'Global' project (Called that because it is the Global Extension whose commands don't have a 'scope')
|
||||
and needs to refer to PerfView to resolve some of its references. Thus you will get many 'not found' issues in the 'Global'
|
||||
project. These can be ignored until you get every other part of the build working.
|
||||
|
||||
###Code Organization
|
||||
### Contributing to PerfView
|
||||
|
||||
You can get a lot of value out of the source code base simply by being able to build the code yourself, debug
|
||||
through it or make add a local, specialized feature. But the real power of open source software happens when
|
||||
you contribute back to shared code base and thus help the community as a whole. **while we encourage this it
|
||||
requires significantly more effort on your part**. If you are interested in stepping up, see the
|
||||
[PerfView Contribution Guide](Contributing.md) and before you start.
|
||||
|
||||
###Code Organization [PerfView Coding Standards](STANDARDS.md)
|
||||
The code is broken in several main sections:
|
||||
* TraceEvent - Library that understands how to decode Event Tracing for Windows (ETW) which is used to actually collect the data for many investigations
|
||||
* TraceEvent - Library that understands how to decode Event Tracing for Windows (ETW) which is used to actually
|
||||
collect the data for many investigations
|
||||
* PerfView - GUI part of the application
|
||||
* MainWindow - GUI code for the window that is initially launched (lets you select files or collect new data)
|
||||
* StackViewer - GUI code for any view with the 'stacks' suffix
|
||||
* EventViewer - GUI code for the 'events' view window
|
||||
* Dialogs - GUI code for a variety of small dialog boxes (although the CollectingDialog is reasonably complex)
|
||||
* Memory - Contains code for memory investigations, in particular it defines 'Graph' and 'MemoryGraph' which are used to display node-arc graphs (e.g. GC heaps)
|
||||
* Memory - Contains code for memory investigations, in particular it defines 'Graph' and 'MemoryGraph' which are used
|
||||
to display node-arc graphs (e.g. GC heaps)
|
||||
|
||||
|
||||
@@ -0,0 +1,77 @@
|
||||
#Coding Standard in the PerfView CodeBase
|
||||
|
||||
|
||||
If you are going to contribute to a code base, you need to 'follow suit'
|
||||
and conform to the standards that are already in place. Here is what
|
||||
PerfView uses.
|
||||
|
||||
##Indenting and other spacing conventions.
|
||||
|
||||
There PerfView code base was developed using Visual Studio, and uses
|
||||
indenting and spacing standards that are the default in Visual Studio.
|
||||
You can use Ctrl-K Ctrl-D (reformat) to make your code confirm to
|
||||
this.
|
||||
|
||||
##Layout of a Class
|
||||
|
||||
Items in a class should be ordered and structured to make reading the
|
||||
as a **public contract** easy. In particular
|
||||
|
||||
1. All private items come AFTER all public ones and are surroudned
|
||||
by a '#region private' grouping. This makes Visual Studio's
|
||||
outlining feature (Ctrl-M Ctrl-O) collapse things so that you
|
||||
only see the public contract for the class.
|
||||
|
||||
|
||||
2. Public methods should be ordered so that constructors or other
|
||||
'generators' are first, then properties then methods.
|
||||
|
||||
3. To the degree possible the most important/common methods should
|
||||
come first in the class, and methods that are used together
|
||||
should be near each other.
|
||||
|
||||
4. Fields should be private and placed TOGETHER LAST in the class
|
||||
(In the #region private). That makes it relatively easy for
|
||||
developer to find all the state in an object (since that is what
|
||||
really defines its semantics.
|
||||
|
||||
##Naming conventions
|
||||
|
||||
1. We follow standard .NET Naming conventions (PascalCase for Types
|
||||
methods and properties, camelCase for parameters and local variables)
|
||||
|
||||
2. Private instance field names begin with a m_ (member). It is also
|
||||
acceptable to use the class library convention of omitting the m (thus prefix
|
||||
instance fields begin with _) If the field is static the prefix is s_.
|
||||
Embedding the type in the variable (Hungarian notation) is NOT used.
|
||||
|
||||
3. Pick descriptive names. Visual Studio makes it easy to rename a
|
||||
variable so fix the name if it 'morphed' as the code was written.
|
||||
|
||||
##Miniumum Comenting
|
||||
|
||||
PerfView is probably commented more than most code bases. We wish
|
||||
to keep it that way. Here is what is expected.
|
||||
|
||||
1. If the type is public (outside the assembly) it needs a comment
|
||||
and all its public members need comments.
|
||||
|
||||
2. Comments before declarations must follow the XML commenting conventions.
|
||||
using the three slashes to indicat this.
|
||||
However typically it is not necessary to explain each parameter
|
||||
to a method (since you gave them really good names, right).
|
||||
You can simply use the Summary tag and omitt the rest (but put
|
||||
the important information in the summary tag).
|
||||
|
||||
3. Field variables of a class typically DO need commenting. This is
|
||||
especially true if there is some condtion (invariant) that is maintained
|
||||
for that variable. These are VERY valuable to document.
|
||||
|
||||
##When in Doubt
|
||||
|
||||
When in doubt, make your code look like the code around it. You can't
|
||||
go too far wrong if you do that.
|
||||
|
||||
## See Also
|
||||
* [PerfView ReadMe](README.md)
|
||||
* [PerfView Contribution Guide](CONTRIBUTING.md)
|
||||
@@ -206,7 +206,7 @@ namespace FastSerialization
|
||||
///
|
||||
/// Call 'GetBytes' call to get the raw array. Only the first 'Length' bytes are valid
|
||||
/// </summary>
|
||||
public MemoryStreamWriter(int initialSize=64)
|
||||
public MemoryStreamWriter(int initialSize = 64)
|
||||
{
|
||||
bytes = new byte[initialSize];
|
||||
}
|
||||
@@ -233,7 +233,7 @@ namespace FastSerialization
|
||||
/// The the array that holds the serialized data.
|
||||
/// </summary>
|
||||
/// <returns></returns>
|
||||
public virtual byte[] GetBytes() { return bytes; }
|
||||
public virtual byte[] GetBytes() { return bytes; }
|
||||
|
||||
/// <summary>
|
||||
/// Clears any data that was previously written.
|
||||
@@ -381,7 +381,7 @@ namespace FastSerialization
|
||||
internal /* protected */ int endPosition;
|
||||
#endregion
|
||||
}
|
||||
#else
|
||||
#else
|
||||
/// <summary>
|
||||
/// A StreamWriter is an implementation of the IStreamWriter interface that generates a byte[] array.
|
||||
/// </summary>
|
||||
@@ -651,7 +651,7 @@ namespace FastSerialization
|
||||
lock (inputStream)
|
||||
{
|
||||
inputStream.Seek(positionInStream + endPosition, SeekOrigin.Begin);
|
||||
for (; ; )
|
||||
for (;;)
|
||||
{
|
||||
System.Threading.Thread.Sleep(0); // allow for Thread.Interrupt
|
||||
int count = inputStream.Read(bytes, endPosition, bytes.Length - endPosition);
|
||||
@@ -687,7 +687,8 @@ namespace FastSerialization
|
||||
/// </summary>
|
||||
public PinnedStreamReader(string fileName, int bufferSize = defaultBufferSize)
|
||||
: this(new FileStream(fileName, FileMode.Open, FileAccess.Read,
|
||||
FileShare.Read | FileShare.Delete), bufferSize) { }
|
||||
FileShare.Read | FileShare.Delete), bufferSize)
|
||||
{ }
|
||||
|
||||
/// <summary>
|
||||
/// Create a new PinnedStreamReader that gets its data from a given System.IO.Stream. You can optionally set the size of the read buffer.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
Microsoft Visual Studio Solution File, Format Version 12.00
|
||||
# Visual Studio 14
|
||||
VisualStudioVersion = 14.0.24720.0
|
||||
VisualStudioVersion = 14.0.25123.0
|
||||
MinimumVisualStudioVersion = 10.0.40219.1
|
||||
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TraceEvent", "..\traceEvent\TraceEvent.csproj", "{B68F4968-A7CF-41CC-AD6E-373DB5E67944}"
|
||||
EndProject
|
||||
@@ -16,9 +16,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Zip", "..\Zip\Zip.csproj",
|
||||
EndProject
|
||||
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{A4068F9B-607A-4531-98A8-DE9B392C2D2C}"
|
||||
ProjectSection(SolutionItems) = preProject
|
||||
..\..\CONTRIBUTING.md = ..\..\CONTRIBUTING.md
|
||||
Local.testsettings = Local.testsettings
|
||||
PerfView2.vsmdi = PerfView2.vsmdi
|
||||
..\..\README.md = ..\..\README.md
|
||||
..\..\STANDARDS.md = ..\..\STANDARDS.md
|
||||
EndProjectSection
|
||||
EndProject
|
||||
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "HeapDumpInterface", "..\HeapDumpInterface\HeapDumpInterface.csproj", "{CE854091-F55D-4AD1-AA57-49CB9B60CAC0}"
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>PerfView User's Guide</title>
|
||||
|
||||
Reference in New Issue
Block a user