From 414744e69261d3e1f9814b7c5d4d3fcef3c2db25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20K=C3=B6plinger?= Date: Mon, 23 Sep 2019 11:09:42 +0200 Subject: [PATCH] Fix a bunch of markdownlint warnings --- .markdownlint.json | 3 +- _posts/2018-12-06-souper.md | 10 +- ...l-version-control-stack-built-with-mono.md | 438 +++++++++--------- _posts/_TEMPLATE.md | 14 +- community/google-summer-of-code/projects.md | 50 +- docs/about-mono/releases/5.16.0.md | 19 +- docs/about-mono/releases/5.18.0.md | 8 +- docs/about-mono/releases/5.20.0.md | 3 - docs/about-mono/releases/6.0.0.md | 24 +- docs/about-mono/releases/6.4.0.md | 3 - docs/advanced/mono-llvm.md | 3 +- docs/compiling-mono/mac/index.md | 4 +- docs/compiling-mono/windows/index.md | 22 +- docs/debug+profile/debug/lldb-source-map.md | 28 +- docs/debug+profile/debug/telemetry.md | 117 +++-- docs/getting-started/install/linux/index.md | 4 +- docs/getting-started/mono-basics.md | 5 +- docs/gui/gtksharp/beginners-guide.md | 66 +-- 18 files changed, 405 insertions(+), 416 deletions(-) diff --git a/.markdownlint.json b/.markdownlint.json index e10e0788c..5fa93a462 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -13,5 +13,6 @@ "MD006": false, "MD007": false, "MD030": false, - "MD032": false + "MD032": false, + "MD046": false } \ No newline at end of file diff --git a/_posts/2018-12-06-souper.md b/_posts/2018-12-06-souper.md index 235ceb5ad..66dfce2a4 100644 --- a/_posts/2018-12-06-souper.md +++ b/_posts/2018-12-06-souper.md @@ -12,7 +12,7 @@ optimizations in our emitted code. The .NET community may have software projects that benefit from using Souper directly to generate code, rather than waiting for us to find ways to automate those optimizations ourselves. This algorithm can generate code that would be very challenging -for a traditional compiler to find. +for a traditional compiler to find. The Mono .NET VM is a rather nimble beast. Rather than requiring all users to live with the performance characteristics of a given policy, we @@ -97,9 +97,9 @@ commandline flags named there into the `---aot=llvmopts=` argument. As of the time of this writing, that is +```bash +llvmopts="-load /path/to/libsouperPass.so -souper -z3-path=/usr/bin/z3" ``` -llvmopts="-load /path/to/libsouperPass.so -souper -z3-path=/usr/bin/z3" -``` Mono will then allow Souper to step in during the middle of the LLVM compilation and try it's best at brute-forcing some better code. If @@ -114,6 +114,4 @@ flexibility of LLVM as a code generation framework and to Mono as an embedded ru Embedders using Mono should consider using our LLVM backend with this and other third-party LLVM optimization passes. Feedback about the impact of our research on real-world programs will help us decide what we -should be using by default. - - +should be using by default. diff --git a/_posts/2019-02-13-plastic-scm-a-full-version-control-stack-built-with-mono.md b/_posts/2019-02-13-plastic-scm-a-full-version-control-stack-built-with-mono.md index 9bb5949e2..0c96e4324 100644 --- a/_posts/2019-02-13-plastic-scm-a-full-version-control-stack-built-with-mono.md +++ b/_posts/2019-02-13-plastic-scm-a-full-version-control-stack-built-with-mono.md @@ -1,219 +1,219 @@ ---- -layout: blog -title: "Plastic SCM: A Full Version Control Stack built with Mono" -author: Jordi Mon Companys -tags: [version control, semantic merge] ---- - -*Note: This is a guest post by Jordi Mon Companys from Códice Software, a long-time Mono user, about how they used Mono to develop their flagship product.* - -[Plastic SCM](https://www.plasticscm.com?utm_source=Mono%20Blog&utm_medium=post&utm_campaign=Mono%20success%20story&utm_term=DotNet&utm_content=Open%20Source) -is a full version control stack. This means Plastic SCM -comprises a full repo management core, command line (until here it would -be the equivalent to bare Git), native GUIs on Linux, macOS and Windows, -web interfaces, diff and merge tools (the equivalent to Meld, WinMerge -or Kdiff3), and also a cloud hosting for repositories. Add Visual Studio -plugins, integrations with the major Continuous Integration systems, -IDEs and issue trackers. - -Plastic SCM was first released in 2006 and didn\'t stop evolving in the -last 13+ years, with 2-3 new public versions every week for the last 2 years. - -Overall Plastic SCM sums more than 1.5 million lines of code and 95% of -them written in C\#. This means we have extensively used Mono for everything -non-Windows since the very early days, now almost a decade and a half -ago. - -And here goes the story. - -Mono shone light down the cross-platform way -============================================ - -When the first lines of Plastic SCM were written back in September 2005, -the decision to go for C\# was already made. But we knew a new version -control system could only be considered as a serious alternative if it -was truly cross-platform. Windows-only was not a choice. - -Why then, we decided to go for .NET/C\# instead of something more -portable like Java, or C/C++? The reason was clear: because Mono -existed. We had never decided to use C\# if Mono hadn\'t been there already. -It promised a way to have cross-platform .NET and we invested heavily on -it. How did it work out? Read along fellow monkeys! - -Fun with cross-platform WinForms --------------------------------- - -Code once, run everywhere. That\'s what we embraced when we started -doing our first tests with WinForms on Linux. - -![Plastic 1 on Linux](/images/2019-02-13-plastic-scm-mono/plastic-1-on-linux.jpg) - -With very minor changes, the full Windows version was able to run on -Linux and macOS (through X11). We later rewrote most of the controls we -were using on WinForms to give them a more consistent look and feel: - -![Plastic 2 on Linux](/images/2019-02-13-plastic-scm-mono/plastic-2-on-linux.jpg) - -![Plastic 2 on Linux](/images/2019-02-13-plastic-scm-mono/plastic-2-on-linux-2.jpg) - -We also did this as a workaround to basically skip some well-known -issues with some standard controls. Obviously, desktop GUIs were not a -big thing in Mono, and we felt like pioneers finding our way through a -wild territory :-) - -Mono on Solaris - a story from the good-old days ------------------------------------------------- - -Something many won\'t know is that for a couple of years we were the -unofficial maintainers of the [Mono port for -Solaris](http://blog.plasticscm.com/2010/10/welcome-crazy-monkeys-mono-on-solaris.html?utm_source=Mono%20Blog&utm_medium=post&utm_campaign=Mono%20success%20story&utm_term=DotNet&utm_content=Open%20Source). - -We were lucky enough to hire a former Mono hacker, our friend Dick -Porter, who enrolled to help us porting Plastic SCM to exotic platforms -like Solaris and HP-UX. - -By that time, we still relied on WinForms everywhere, which was a -challenge on its own. - -You can see how Plastic SCM running on Solaris looked like: - -![Plastic 2.7 on Solaris](/images/2019-02-13-plastic-scm-mono/plastic-2.7-on-solaris-cde.jpg) - -And: - -![Plastic on Solaris SPARC](/images/2019-02-13-plastic-scm-mono/plastic-on-solaris-sparc.png) - -We were super excited about it because it allowed us to run Plastic SCM -on some old Sun workstations we had around. And they featured SPARC -CPUs, 64-bit big endian and everything. In fact, we found and protected -some edge cases caused by big endian :-). - -From Boehm to sgen ------------------- - -We were hit by some of the limitations of Boehm GC, so we happily -provided the developers working on the new sgen collector with a memory -hungry Plastic SCM environment. We used to run some memory intensive -automated tests for them so we mutually benefit from the effort. - -This was mostly before everyone moved to the cloud, so we ran most of -these tests in about 300 real machines controlled by our in-house PNUnit -test environment. - -Native GUIs ------------ - -Depending on X11 to run our GUI on macOS wasn\'t greatly perceived by -hardcore Apple users who prefer a smooth experience. So, we decided to -radically change our approach to GUI development. We committed to create -native GUIs for each of our platforms. - -- Windows would still benefit from the same original codebase. But, - removing the common denominator requirements allowed us to introduce - new controls and enrich the overall experience. - -- The macOS GUI would be rewritten taking advantage of MonoMac, which - later became XamarinMac, the technology we still use. It was going - to be an entirely new codebase that only shared the core operations - with Windows, while the entire intermediate layer would be developed - from scratch. - -- And finally, we decided to go for a native GTKSharp-based GUI for - Linux. In fact, it would be a good exercise to see how much of the - common layer could be actually shared between macOS and Linux. It - worked quite well. - -Some takeaways from this new approach: - -- We decided to entirely skip \"visual designer tools\". ResX on - WinForms proved to be a nightmare when used cross-platform, and - depending on locating controls by hand with a designer on a canvas - wasn\'t good to keep consistent margins, spacing and so on. So, we - went cowboy: every single GUI you see in Plastic SCM now (except the - older ones in WinForms) is basically coded, not designed. Every - button is created with \"new Button()\", and so on. It can sound - like a slowdown, but it certainly pays off when maintaining code: - you spend much [less time dealing with code than - designers](http://blog.semanticmerge.com/2014/03/gui-development-design-or-code-imperative.html?utm_source=Mono%20Blog&utm_medium=post&utm_campaign=Mono%20success%20story&utm_term=DotNet&utm_content=Open%20Source). - -- We created our own [automated GUI test - environment](http://blog.plasticscm.com/2019/01/guitestsharp-multiplatform-gui-testing-dotnet.html?utm_source=Mono%20Blog&utm_medium=post&utm_campaign=Mono%20success%20story&utm_term=DotNet&utm_content=Open%20Source) - to test the Linux and macOS GUIs. There weren\'t any cross-platform - solutions for Mono, so we decided to create our own. - -- We realized how much better GTK was and is than any other solution - from a programmer's perspective. We love to code GTK. Yes, it is - also possibly the ugliest in visual terms of them all, but you - can\'t have it all :-) - -This is how Plastic SCM looks now, enjoy: - -![Mac Branch Explorer](/images/2019-02-13-plastic-scm-mono/macplastic-brex.png) - -![Windows Diff Window](/images/2019-02-13-plastic-scm-mono/windows-diff-window.png) - -![Windows Branch Explorer](/images/2019-02-13-plastic-scm-mono/windows-brex.png) - -But wait! Wouldn't Mono affect performance? Baby, we are built for speed! -------------------------------------------------------------------------- - -Many of you might think: how can a version control be written in -Mono/C\# and expect to compete against Git or Subversion or even -Perforce which are all written in C or a C/C++ combination? - -Speed was an obsession for us since day one, and we found C\# to be -quite capable if used carefully. The only downside is that when you are -in a C\#/managed world you tend to think allocating memory is free and -you pay for it when that happens (something that radically changed with -the arrival of .NET Core and the entire Span\ and their focus on -making the platform a real option for highly scalable and performant -solutions). But, over the years we learned a few lessons, started to be -much more aware of the importance of saving allocations, and the results -backed up that reasoning. - -Below you can see how a 2019 version of Plastic SCM compares to Git and -a major commercial version control competitor performing quite common -operations: - -![Performance Benchmark](/images/2019-02-13-plastic-scm-mono/performance-benchmark.png) - -As you can see, Plastic SCM consistently beats Git, which we believe is -quite an achievement considering it is written in .NET/Mono/C\# instead -of system-level C. - -Heavy loaded servers --------------------- - -In terms of pure scalability, we also achieve quite good results -compared to commercial version controls: - -![Scalability Benchmark](/images/2019-02-13-plastic-scm-mono/scalability-benchmark.png) - -We don\'t compare to Git here since what we are running are pure -centralized operations (direct checkin or commit if you prefer) -something Git can\'t do. Plastic SCM can work in Git or SVN modes, local -repos or direct connection to a central server. - -In fact, some of our highest loaded servers on production run on -Linux/Mono serving more than 3000 developers on a big enterprise setup. -A single server handles most of the load singlehandedly :-) - -Mono is indeed for code monkeys -------------------------------- - -If you've read the whole use case you already know that we have been -using Mono for the purpose of providing a full version control stack -since 2006! That is for almost 13 years, right after the company was -founded and the first product of our portfolio was delivered. - -After all this time it has helped us build and distribute the same -product across the different environments: a full stack version control -system that is pioneering software configuration management in many -areas. The results are there and hey, we are demanding: versatility, -performance, scalability and resilience are not an option for our -clients, or us. Given the structural relevance of SCM tools to any -software project, it is paramount for Plastic SCM to deliver a solid -product across all platforms, and we do it. To us Mono = cross-platform -and that is a huge advantage since we can focus on functionality, -roadmap and support while Mono makes the product one same experience -everywhere. Mono is definitely a foundational part of toolkit. +--- +layout: blog +title: "Plastic SCM: A Full Version Control Stack built with Mono" +author: Jordi Mon Companys +tags: [version control, semantic merge] +--- + +*Note: This is a guest post by Jordi Mon Companys from Códice Software, a long-time Mono user, about how they used Mono to develop their flagship product.* + +[Plastic SCM](https://www.plasticscm.com?utm_source=Mono%20Blog&utm_medium=post&utm_campaign=Mono%20success%20story&utm_term=DotNet&utm_content=Open%20Source) +is a full version control stack. This means Plastic SCM +comprises a full repo management core, command line (until here it would +be the equivalent to bare Git), native GUIs on Linux, macOS and Windows, +web interfaces, diff and merge tools (the equivalent to Meld, WinMerge +or Kdiff3), and also a cloud hosting for repositories. Add Visual Studio +plugins, integrations with the major Continuous Integration systems, +IDEs and issue trackers. + +Plastic SCM was first released in 2006 and didn\'t stop evolving in the +last 13+ years, with 2-3 new public versions every week for the last 2 years. + +Overall Plastic SCM sums more than 1.5 million lines of code and 95% of +them written in C\#. This means we have extensively used Mono for everything +non-Windows since the very early days, now almost a decade and a half +ago. + +And here goes the story. + +Mono shone light down the cross-platform way +============================================ + +When the first lines of Plastic SCM were written back in September 2005, +the decision to go for C\# was already made. But we knew a new version +control system could only be considered as a serious alternative if it +was truly cross-platform. Windows-only was not a choice. + +Why then, we decided to go for .NET/C\# instead of something more +portable like Java, or C/C++? The reason was clear: because Mono +existed. We had never decided to use C\# if Mono hadn\'t been there already. +It promised a way to have cross-platform .NET and we invested heavily on +it. How did it work out? Read along fellow monkeys! + +Fun with cross-platform WinForms +-------------------------------- + +Code once, run everywhere. That\'s what we embraced when we started +doing our first tests with WinForms on Linux. + +![Plastic 1 on Linux](/images/2019-02-13-plastic-scm-mono/plastic-1-on-linux.jpg) + +With very minor changes, the full Windows version was able to run on +Linux and macOS (through X11). We later rewrote most of the controls we +were using on WinForms to give them a more consistent look and feel: + +![Plastic 2 on Linux](/images/2019-02-13-plastic-scm-mono/plastic-2-on-linux.jpg) + +![Plastic 2 on Linux](/images/2019-02-13-plastic-scm-mono/plastic-2-on-linux-2.jpg) + +We also did this as a workaround to basically skip some well-known +issues with some standard controls. Obviously, desktop GUIs were not a +big thing in Mono, and we felt like pioneers finding our way through a +wild territory :-) + +Mono on Solaris - a story from the good-old days +------------------------------------------------ + +Something many won\'t know is that for a couple of years we were the +unofficial maintainers of the [Mono port for +Solaris](http://blog.plasticscm.com/2010/10/welcome-crazy-monkeys-mono-on-solaris.html?utm_source=Mono%20Blog&utm_medium=post&utm_campaign=Mono%20success%20story&utm_term=DotNet&utm_content=Open%20Source). + +We were lucky enough to hire a former Mono hacker, our friend Dick +Porter, who enrolled to help us porting Plastic SCM to exotic platforms +like Solaris and HP-UX. + +By that time, we still relied on WinForms everywhere, which was a +challenge on its own. + +You can see how Plastic SCM running on Solaris looked like: + +![Plastic 2.7 on Solaris](/images/2019-02-13-plastic-scm-mono/plastic-2.7-on-solaris-cde.jpg) + +And: + +![Plastic on Solaris SPARC](/images/2019-02-13-plastic-scm-mono/plastic-on-solaris-sparc.png) + +We were super excited about it because it allowed us to run Plastic SCM +on some old Sun workstations we had around. And they featured SPARC +CPUs, 64-bit big endian and everything. In fact, we found and protected +some edge cases caused by big endian :-). + +From Boehm to sgen +------------------ + +We were hit by some of the limitations of Boehm GC, so we happily +provided the developers working on the new sgen collector with a memory +hungry Plastic SCM environment. We used to run some memory intensive +automated tests for them so we mutually benefit from the effort. + +This was mostly before everyone moved to the cloud, so we ran most of +these tests in about 300 real machines controlled by our in-house PNUnit +test environment. + +Native GUIs +----------- + +Depending on X11 to run our GUI on macOS wasn\'t greatly perceived by +hardcore Apple users who prefer a smooth experience. So, we decided to +radically change our approach to GUI development. We committed to create +native GUIs for each of our platforms. + +- Windows would still benefit from the same original codebase. But, + removing the common denominator requirements allowed us to introduce + new controls and enrich the overall experience. + +- The macOS GUI would be rewritten taking advantage of MonoMac, which + later became XamarinMac, the technology we still use. It was going + to be an entirely new codebase that only shared the core operations + with Windows, while the entire intermediate layer would be developed + from scratch. + +- And finally, we decided to go for a native GTKSharp-based GUI for + Linux. In fact, it would be a good exercise to see how much of the + common layer could be actually shared between macOS and Linux. It + worked quite well. + +Some takeaways from this new approach: + +- We decided to entirely skip \"visual designer tools\". ResX on + WinForms proved to be a nightmare when used cross-platform, and + depending on locating controls by hand with a designer on a canvas + wasn\'t good to keep consistent margins, spacing and so on. So, we + went cowboy: every single GUI you see in Plastic SCM now (except the + older ones in WinForms) is basically coded, not designed. Every + button is created with \"new Button()\", and so on. It can sound + like a slowdown, but it certainly pays off when maintaining code: + you spend much [less time dealing with code than + designers](http://blog.semanticmerge.com/2014/03/gui-development-design-or-code-imperative.html?utm_source=Mono%20Blog&utm_medium=post&utm_campaign=Mono%20success%20story&utm_term=DotNet&utm_content=Open%20Source). + +- We created our own [automated GUI test + environment](http://blog.plasticscm.com/2019/01/guitestsharp-multiplatform-gui-testing-dotnet.html?utm_source=Mono%20Blog&utm_medium=post&utm_campaign=Mono%20success%20story&utm_term=DotNet&utm_content=Open%20Source) + to test the Linux and macOS GUIs. There weren\'t any cross-platform + solutions for Mono, so we decided to create our own. + +- We realized how much better GTK was and is than any other solution + from a programmer's perspective. We love to code GTK. Yes, it is + also possibly the ugliest in visual terms of them all, but you + can\'t have it all :-) + +This is how Plastic SCM looks now, enjoy: + +![Mac Branch Explorer](/images/2019-02-13-plastic-scm-mono/macplastic-brex.png) + +![Windows Diff Window](/images/2019-02-13-plastic-scm-mono/windows-diff-window.png) + +![Windows Branch Explorer](/images/2019-02-13-plastic-scm-mono/windows-brex.png) + +But wait! Wouldn't Mono affect performance? +------------------------------------------- + +Many of you might think: how can a version control be written in +Mono/C\# and expect to compete against Git or Subversion or even +Perforce which are all written in C or a C/C++ combination? + +Speed was an obsession for us since day one, and we found C\# to be +quite capable if used carefully. The only downside is that when you are +in a C\#/managed world you tend to think allocating memory is free and +you pay for it when that happens (something that radically changed with +the arrival of .NET Core and the entire Span\ and their focus on +making the platform a real option for highly scalable and performant +solutions). But, over the years we learned a few lessons, started to be +much more aware of the importance of saving allocations, and the results +backed up that reasoning. + +Below you can see how a 2019 version of Plastic SCM compares to Git and +a major commercial version control competitor performing quite common +operations: + +![Performance Benchmark](/images/2019-02-13-plastic-scm-mono/performance-benchmark.png) + +As you can see, Plastic SCM consistently beats Git, which we believe is +quite an achievement considering it is written in .NET/Mono/C\# instead +of system-level C. + +Heavy loaded servers +-------------------- + +In terms of pure scalability, we also achieve quite good results +compared to commercial version controls: + +![Scalability Benchmark](/images/2019-02-13-plastic-scm-mono/scalability-benchmark.png) + +We don\'t compare to Git here since what we are running are pure +centralized operations (direct checkin or commit if you prefer) +something Git can\'t do. Plastic SCM can work in Git or SVN modes, local +repos or direct connection to a central server. + +In fact, some of our highest loaded servers on production run on +Linux/Mono serving more than 3000 developers on a big enterprise setup. +A single server handles most of the load singlehandedly :-) + +Mono is indeed for code monkeys +------------------------------- + +If you've read the whole use case you already know that we have been +using Mono for the purpose of providing a full version control stack +since 2006! That is for almost 13 years, right after the company was +founded and the first product of our portfolio was delivered. + +After all this time it has helped us build and distribute the same +product across the different environments: a full stack version control +system that is pioneering software configuration management in many +areas. The results are there and hey, we are demanding: versatility, +performance, scalability and resilience are not an option for our +clients, or us. Given the structural relevance of SCM tools to any +software project, it is paramount for Plastic SCM to deliver a solid +product across all platforms, and we do it. To us Mono = cross-platform +and that is a huge advantage since we can focus on functionality, +roadmap and support while Mono makes the product one same experience +everywhere. Mono is definitely a foundational part of toolkit. diff --git a/_posts/_TEMPLATE.md b/_posts/_TEMPLATE.md index 03005d1c5..982f90524 100644 --- a/_posts/_TEMPLATE.md +++ b/_posts/_TEMPLATE.md @@ -1,7 +1,7 @@ --- layout: blog title: "" -author: +author: tags: [] --- @@ -10,10 +10,10 @@ The blog post goes here... To complete your blog post, simply follow the steps below. (don't edit original `_TEMPLATE.md` file). 1. Fill out the above fields: title, author, and tags. - -layout: Leave it with blog. - -title: Title of your blog post - -author: Your name or the person who wrote this post. - -tags: tag of the blog post. + -layout: Leave it with blog. + -title: Title of your blog post + -author: Your name or the person who wrote this post. + -tags: tag of the blog post. 2. Delete all of this instructional text and replace it with the actual content. @@ -22,6 +22,6 @@ To complete your blog post, simply follow the steps below. (don't edit original Hint: This file uses Markdown formatting. You can use Markdown to add emphasis to your text, link to projects you've worked on, or link to files you'd like to share such as your resume. Here are some resources on learning Markdown: - - https://guides.github.com/features/mastering-markdown/ - a reference + - - a reference guide - - http://www.markdowntutorial.com/ - a more comprehensive tutorial \ No newline at end of file + - - a more comprehensive tutorial diff --git a/community/google-summer-of-code/projects.md b/community/google-summer-of-code/projects.md index 734122c08..5fc5d24b5 100644 --- a/community/google-summer-of-code/projects.md +++ b/community/google-summer-of-code/projects.md @@ -185,15 +185,15 @@ Optional: **Complexity:** Hard -Superoptimization is a method for generating provably-optimal code for short segments of logical operations. The process of stitching these together had classically been seen as intractable, but modern optimizations of the process makes it doable, if a bit slow. +Superoptimization is a method for generating provably-optimal code for short segments of logical operations. The process of stitching these together had classically been seen as intractable, but modern optimizations of the process makes it doable, if a bit slow. -Production applications sometimes would benefit from much faster code, even at the cost of compilation time and the audibility of compilation. +Production applications sometimes would benefit from much faster code, even at the cost of compilation time and the audibility of compilation. -This project would see the student do further build and automation work to enable us to use Souper out-of-the box. Creation of some diagrams and benchmarks showing the cost and improvements with Souper would be one deliverable as well. +This project would see the student do further build and automation work to enable us to use Souper out-of-the box. Creation of some diagrams and benchmarks showing the cost and improvements with Souper would be one deliverable as well. This student can hope to gain some familiarity with binding LLVM and working with the LLVM tooling ecosystem. -https://www.mono-project.com/news/2018/12/06/souper/ + **Mentors:** Alexander Kyte @@ -217,10 +217,10 @@ Flatpak is all the rage these days in the Open Source and GNOME community. It's Ideas for Flatpak + Mono tools: -- An extension for MonoDevelop that turns any C# project into a Flatpak -- A flatpak-builder extension that includes the Mono runtime to save time/space when compiling a bundle -- A tool that uses mkbundle to statically link the entire app and keep mono based flatpak bundles small -- Templates for easy inclusion of open source NuGets +* *An extension for MonoDevelop that turns any C# project into a Flatpak +* *A flatpak-builder extension that includes the Mono runtime to save time/space when compiling a bundle +* *A tool that uses mkbundle to statically link the entire app and keep mono based flatpak bundles small +* *Templates for easy inclusion of open source NuGets **Deliverables**: An end-to-end experience for creating a Flatpak from a MonoDevelop project @@ -232,7 +232,7 @@ Ideas for Flatpak + Mono tools: A proof of concept has been demonstrated using Julia's [LLVM C Backend](https://github.com/JuliaComputing/llvm-cbe) with Mono to generate C code from a managed executable. This would allow using Mono on older/limited/exotic platforms where it cannot currently be used. -For details, see https://github.com/mono/mono/issues/11940 +For details, see The project is to make this more complete and stable. A key part of this would be to make the backend use Mono's intrinsics instead of LLVM-CBE's Julia-specific intrinsics. @@ -273,12 +273,12 @@ Notes: it does not have to use (or hack around) the latest Cecil, e.g. it could **Complexity:** Hard There was some initial bootstrapping done for RISC-V: -https://github.com/mono/mono/pull/11593 + I see two projects possible around this area: -- (1) continue implementing the JIT backend. I wouldn't expect a student to get it to a "complete" state after two months, but the delivery can be reduced to "make the mini regression test suite work", which is a huge achievement, but not a fully working runtime. -- (2) get the interpreter working on this target. This needs some low-level hacking in terms of writing RISC-V assembly. However, it's a fairly contained work item and as a reward it should be able to run almost anything (as the interpreter itself is pretty complete). +* (1) continue implementing the JIT backend. I wouldn't expect a student to get it to a "complete" state after two months, but the delivery can be reduced to "make the mini regression test suite work", which is a huge achievement, but not a fully working runtime. +* (2) get the interpreter working on this target. This needs some low-level hacking in terms of writing RISC-V assembly. However, it's a fairly contained work item and as a reward it should be able to run almost anything (as the interpreter itself is pretty complete). Note1: I would not recommend using the LLVM backend, because it needs the regular JIT backend as a fallback. @@ -413,19 +413,19 @@ What if we used a database (such as SQLlite or [LMDB](https://github.com/LMDB/lm RR is a debugger that allows for recording of execution in a way that can be replayed later in a debugger. The results of syscalls are fed back into the program to replicate the environment the program saw over time. -The runtime can be debugged with RR on linux, but this is mostly useful for low-level debugging. +The runtime can be debugged with RR on linux, but this is mostly useful for low-level debugging. We have two options here: We can expose managed logging and heap/stack snapshotting to the debugger-agent and do this is a managed way. This allows us to work on ARM, linux, windows, ios, etc. The downside is that we don't get to replay state changes in unmanaged code. -Alternatively, we can have the student create glue code for using rr to debug the entire runtime remotely, and add in the hooks to get the information on managed methods from the runtime. Someone can then record a crash on their machine as it is happening, and submit it with a bug report. +Alternatively, we can have the student create glue code for using rr to debug the entire runtime remotely, and add in the hooks to get the information on managed methods from the runtime. Someone can then record a crash on their machine as it is happening, and submit it with a bug report. -I believe that the latter idea would make bug reports an order of magnitude more useful. By removing the difficulty of reproducing crashes, we may save our own developers a lot of time. +I believe that the latter idea would make bug reports an order of magnitude more useful. By removing the difficulty of reproducing crashes, we may save our own developers a lot of time. Deliverables: -- Get RR debugging of mono working interactively -- Create automated RR client that records and replays mono -- Create infrastructure to use RR client and create self contained "debug me" blob +* Get RR debugging of mono working interactively +* Create automated RR client that records and replays mono +* Create infrastructure to use RR client and create self contained "debug me" blob **Mentors:** Bernhard Urban @@ -433,7 +433,7 @@ Deliverables: **Complexity:** Medium -Bitmask-driven data structures allow for SIMD operations on the data structure's top-level structure schema. They're space-efficient, cache-efficient, and they're easy to debug after a crash because the bitmask and the data structure have a minimal number of pointers. +Bitmask-driven data structures allow for SIMD operations on the data structure's top-level structure schema. They're space-efficient, cache-efficient, and they're easy to debug after a crash because the bitmask and the data structure have a minimal number of pointers. Offering succinct arrays (no nulls) and other data structures as drop-in replacements might be ways to significantly reduce memory footprint for some specific use cases. @@ -441,13 +441,13 @@ Benchmarking is necessary to find those use-cases. Deliverables: -- Implement full replacement for GArray and ensure passes GLib GArray tests. +* Implement full replacement for GArray and ensure passes GLib GArray tests. -- Benchmark high-allocation places and see if the succinct replacement helps +* Benchmark high-allocation places and see if the succinct replacement helps -- (Optional) Implement replacement for ghashtable which supports bare minimum of operations, using CTries +* (Optional) Implement replacement for ghashtable which supports bare minimum of operations, using CTries -- (Optional) Use CTries in high-contention environments or high-allocation environments and benchmark uses that have savings +* (Optional) Use CTries in high-contention environments or high-allocation environments and benchmark uses that have savings **Mentors:** Alexander Kyte @@ -473,11 +473,11 @@ This effort would use the Dart compiler to process the Flutter API and output th **Complexity:** Medium We have a C# binding for the SEAL homomorphic encryption library. -https://www.microsoft.com/en-us/research/project/simple-encrypted-arithmetic-library/ + The current status is that we can work with 64-bit ints and we have the beginnings of a Linq Expression analyzer to automate creating encrypted computations. -https://github.com/lambdageek/sealsharp/tree + Next steps would be to add more bindings (for example, support for floats and matrices), and to work on automating some of the entropy and relinearization key management by taking advantage of the analyzability of Linq expressions. diff --git a/docs/about-mono/releases/5.16.0.md b/docs/about-mono/releases/5.16.0.md index 13f26b95a..c65f9a87e 100644 --- a/docs/about-mono/releases/5.16.0.md +++ b/docs/about-mono/releases/5.16.0.md @@ -5,10 +5,6 @@ version: 5.16.0 releasedate: '2018-10-08' --- -Release History -=============== - - Highlights ========== @@ -44,8 +40,8 @@ Threads that are running managed code or code that is part of the managed runtim In 5.16, hybrid suspend is turned on by default on Linux (amd64 and i386) and macOS. There are `configure` flags and environment variables available to control the suspend mechanism: -- Pass `--enable-hybrid-suspend` to `configure` to turn on hybrid suspend by default. Pass `--disable-hybrid-suspend --disable-cooperative-suspend` to use the old preemptive suspend as the default mechanism. -- At runtime set the environment variable `MONO_THREADS_SUSPEND` to `preemptive` to use preemptive suspend or `hybrid` to use hybrid suspend. +* Pass `--enable-hybrid-suspend` to `configure` to turn on hybrid suspend by default. Pass `--disable-hybrid-suspend --disable-cooperative-suspend` to use the old preemptive suspend as the default mechanism. +* At runtime set the environment variable `MONO_THREADS_SUSPEND` to `preemptive` to use preemptive suspend or `hybrid` to use hybrid suspend. ### 32-bit floating operations @@ -88,14 +84,15 @@ The single-precision math operations are now available in a new `System.MathF` c ### Prettier exception stack-traces Ben Adams has contributed prettier exception printer, especially for generated code stack traces. For example, the async exceptions are now automatically de-mangled and instead of showing -``` + +```text System.ApplicationException: Error in the application. at X+d__1.MoveNext () [0x0006c] in /path/foo.cs:14 <--- ``` the stack trace shows the C# code signature -``` +```text System.ApplicationException: Error in the application. at X.Foo () [0x0006c] in /path/foo.cs:14 <--- ``` @@ -104,9 +101,11 @@ System.ApplicationException: Error in the application. The arbitrary command nesting is now supported. The two new mechanisms were introduced to allow that. The command names may now contain spaces and `CommandSets` may be nested within `CommandSets`. This allows supporting syntax like: -``` +```bash $ azure config mode arm +... $ azure vm create +... ``` ### Automatic proxy configuration @@ -176,7 +175,7 @@ The nuget tool has been updated to the latest 4.8 version (4.8.2). * [#7785](https://github.com/mono/mono/issues/7785) - Dead link (404) in a runtime execution engine exception * [#7828](https://github.com/mono/mono/issues/7828) - Invalid instruction generated by regex runtime when using dapper * [#7944](https://github.com/mono/mono/issues/7944) - CreateDelegate produces delegate wrapping incorrect method -* [#7947](https://github.com/mono/mono/issues/7947) - Missing forwarders from System.Runtime.Extensions +* [#7947](https://github.com/mono/mono/issues/7947) - Missing forwarders from System.Runtime.Extensions * [#8036](https://github.com/mono/mono/issues/8036) - Update API diff to ignore more attributes * [#8074](https://github.com/mono/mono/issues/8074) - signing problems in preset fullaot build * [#8089](https://github.com/mono/mono/issues/8089) - Add System.Drawing.Common facade for Xamarin profiles diff --git a/docs/about-mono/releases/5.18.0.md b/docs/about-mono/releases/5.18.0.md index e37ce694d..fb52f1a54 100644 --- a/docs/about-mono/releases/5.18.0.md +++ b/docs/about-mono/releases/5.18.0.md @@ -5,10 +5,6 @@ version: 5.18.0 releasedate: '2018-12-21' --- -Release History -=============== - - Highlights ========== @@ -25,7 +21,7 @@ Due to limitations in the TLS stack on 10.7 we are updating the minimum macOS de ### AOT -Few hard to track race conditions in trampolines unboxing for AOT backend targetting amd64 were fixed. +Few hard to track race conditions in trampolines unboxing for AOT backend targetting amd64 were fixed. ### Interpreter @@ -58,6 +54,7 @@ A new `CommandSet.GetCompletions()` method was introduced, which returns all pos It's now possible to use `RuntimeInformation` API to detect ARM and ARM64 platforms. ### System.Drawing + Image loading routines have been hardened to have thorough checks for out of range inputs for various codecs. ## Tools @@ -67,6 +64,7 @@ Image loading routines have been hardened to have thorough checks for out of ran Reference assemblies for .NET 4.7.2 are included to allow targeting .NET Framework 4.7.2 using MSBuild on Mono. ### nuget + The nuget tool has been updated to the latest 4.8 version (4.8.2). # Resolved Issues diff --git a/docs/about-mono/releases/5.20.0.md b/docs/about-mono/releases/5.20.0.md index d296782b6..5fb8e4852 100644 --- a/docs/about-mono/releases/5.20.0.md +++ b/docs/about-mono/releases/5.20.0.md @@ -5,9 +5,6 @@ version: 5.20.0 releasedate: '2019-04-11' --- -Release History -=============== - Highlights ========== diff --git a/docs/about-mono/releases/6.0.0.md b/docs/about-mono/releases/6.0.0.md index bd3ee538c..baa4898d4 100644 --- a/docs/about-mono/releases/6.0.0.md +++ b/docs/about-mono/releases/6.0.0.md @@ -5,10 +5,6 @@ version: 6.0.0 releasedate: '2019-07-17' --- -Release History -=============== - - Highlights ========== @@ -23,6 +19,7 @@ This is the first release of new 6.x series with many improvements and bug fixes ## Runtime ### CLI Improvements + New runtime setting called `llcopts` add an option to control arguments to `llc` tool. Use this option to add more flags to the built-in set of flags passed to the LLVM system compiler. If not provided, it will fallback to `-mcpu=generic` on x86 systems. Additional new commands called `llvmopts-add` and `llvmllc-add` have been added to allow simply append additional arguments to LLVM's `opt` and `llc` tools. @@ -30,7 +27,7 @@ Additional new commands called `llvmopts-add` and `llvmllc-add` have been added `mono --aot=llvm,llvmopts-add="-foo",llvmllc-add="-foo"` We have also improved response file handling to work better on Windows. - + ### Interpreter A lot of attention in this release went to stabilizing and testing interpreter support. We have resolved many outstanding issues in handling different IL constructs as well as reported issues on ARM architecture. @@ -52,15 +49,17 @@ Support for more methods available in the newer versions of this special NuGet a Various set of issues and problems with debugger has been resolved or mitigated in this release. They should increase the stability of the debugger when debugging complex issues or multi-threaded applications. Additional features like time recording between debugger steps have been added to the underlying debugger protocol. - + ### System.Math methods optimizations + The constant folding for some Math operations on doubles has been implemented. In particular support for constant folding of additions and multiplications of doubles as well as constant folding of Math.Sin, Math.Cos, Math.Abs and Math.Sqrt. - + ### Initial RISC-V support We have landed experimental support in the interpreter for RISC-V. It's able to run Hello World like C# program with all necessary runtime support. - + ### monograph + This obsolete utility has been removed. ## Class Libraries @@ -121,7 +120,6 @@ We have also included embedded Source Link information to all managed debug symb The support for LLVM integrated build as part of the Visual Studio solution has been added. - # Resolved Issues * [#10024](https://github.com/mono/mono/issues/10024) - Invocation of Array ctor with negative length throws wrong exception @@ -214,18 +212,18 @@ The support for LLVM integrated build as part of the Visual Studio solution has * [#13522](https://github.com/mono/mono/issues/13522) - AOT issue on WatchOS: "* Assertion at mini-llvm.c:9381, condition `fields [2 + i]' not met " * [#13526](https://github.com/mono/mono/issues/13526) - The repl (monotouch_tv_runtime) assemblies don't work for tvOS * [#13607](https://github.com/mono/mono/issues/13607) - Assertion in xamarin-macios link sdk test: "mini-generic-sharing.c:568, condition `is_ok (error)' not met, function:inflate_info, Could not inflate generic type, due to MVAR 0 (T_ULONG) cannot be expanded with type 0x1e" -* [#13610](https://github.com/mono/mono/issues/13610) - Returning tuple broken when enabling fullAOT+LLVM +* [#13610](https://github.com/mono/mono/issues/13610) - Returning tuple broken when enabling fullAOT+LLVM * [#13639](https://github.com/mono/mono/issues/13639) - mono-cil-strip crashes when called against the monotouch_Microsoft.CSharp_xunit-test.dll -* [#13654](https://github.com/mono/mono/issues/13654) - Interpreter Crash When Doing Fancy Reflection +* [#13654](https://github.com/mono/mono/issues/13654) - Interpreter Crash When Doing Fancy Reflection * [#13672](https://github.com/mono/mono/issues/13672) - [2019-02] Xamarin.Android runtime tests crash on free * [#13834](https://github.com/mono/mono/issues/13834) - Mac crash reports do not give the right SizeOfImage * [#13878](https://github.com/mono/mono/issues/13878) - System.Reflection.Emit.DynamicMethod:CreateDelegate (?) crashes XM apps when under hardened runtime * [#13941](https://github.com/mono/mono/issues/13941) - Crash During AOT of ASP.NET Core Assemblies -* [#14079](https://github.com/mono/mono/issues/14079) - Interpreter Crash on Reference Source System.Web.Extensions +* [#14079](https://github.com/mono/mono/issues/14079) - Interpreter Crash on Reference Source System.Web.Extensions * [#14170](https://github.com/mono/mono/issues/14170) - "Fatal signal 11 (SIGSEGV), code 1 (SEGV_MAPERR)" after debugger pauses and then continues on nested exception * [#14214](https://github.com/mono/mono/issues/14214) - HttpClient.SendAsync() with > 2 GB response body. * [#14223](https://github.com/mono/mono/issues/14223) - [2019-02] [watchOS] mini/debug fails on armv7k -* [#14246](https://github.com/mono/mono/issues/14246) - Interpreter crashes when encountering build-in types +* [#14246](https://github.com/mono/mono/issues/14246) - Interpreter crashes when encountering build-in types * [#14247](https://github.com/mono/mono/issues/14247) - Assertion on 32-bit iOS device with thumb code * [#14290](https://github.com/mono/mono/issues/14290) - [ios] Non-public API usage when submitting app * [#14496](https://github.com/mono/mono/issues/14496) - [tests] System test dlls leak symbols on tvOS. diff --git a/docs/about-mono/releases/6.4.0.md b/docs/about-mono/releases/6.4.0.md index e6f2d4cf0..a22f494e0 100644 --- a/docs/about-mono/releases/6.4.0.md +++ b/docs/about-mono/releases/6.4.0.md @@ -5,9 +5,6 @@ version: 6.4.0 releasedate: --- -Release History -=============== - ! PREVIEW VERSION ! Highlights diff --git a/docs/advanced/mono-llvm.md b/docs/advanced/mono-llvm.md index 14e614b2a..b71c25ab2 100644 --- a/docs/advanced/mono-llvm.md +++ b/docs/advanced/mono-llvm.md @@ -24,7 +24,6 @@ source. Also note that most packages are shipped with an LLVM enabled Mono runtime. - Compiling LLVM support for older versions of Mono ================================================= @@ -98,4 +97,4 @@ hosted cross compilers), only x64 Visual Studio builds support LLVM powered Mono runtime. Mono runtime build using mingw only supports LLVM for Windows hosted cross compilers. For more details around regular Mono Windows LLVM builds (**not** building Windows hosted cross -compilers), see [Compiling Mono On Windows](/docs/compiling-mono/windows/) \ No newline at end of file +compilers), see [Compiling Mono On Windows](/docs/compiling-mono/windows/) diff --git a/docs/compiling-mono/mac/index.md b/docs/compiling-mono/mac/index.md index 1230d7bbb..3523c355f 100644 --- a/docs/compiling-mono/mac/index.md +++ b/docs/compiling-mono/mac/index.md @@ -26,7 +26,7 @@ Mono uses GNU autoconf, automake and libtool. You need to install those in your brew install autoconf automake libtool pkg-config cmake ``` ------------------------------------- +--- Mono releases are distributed as .tar.xz packages from the Mono web site. Once you have your dependencies installed all you need to do is run the following command where VERSION is the package version number and PREFIX is your installation prefix: @@ -57,7 +57,7 @@ To build Mono from a Git Source Code checkout, you will want to have the officia PATH=$PREFIX/bin:$PATH git clone https://github.com/mono/mono.git cd mono -./autogen.sh --prefix=$PREFIX --disable-nls +./autogen.sh --prefix=$PREFIX --disable-nls make make install ``` diff --git a/docs/compiling-mono/windows/index.md b/docs/compiling-mono/windows/index.md index 948a434f9..8f4ebfb73 100644 --- a/docs/compiling-mono/windows/index.md +++ b/docs/compiling-mono/windows/index.md @@ -44,6 +44,7 @@ cd mono Pre-configured build instructions, building a default Visual Studio Mono runtime, mingw Mono runtime, Mono BCL and install into `PREFIX`. For further detailed build configurations and instructions, see next section. Run one of the following set of commands from a Cygwin command prompt after all steps in section above have been completed. 64-bit Mono runtime using SGEN GC and default BCL profile (net_4_x): + ```bash ./autogen.sh --prefix=$PREFIX --host=x86_64-w64-mingw32 --enable-msvc --disable-boehm make -j4 @@ -51,6 +52,7 @@ make install ``` 32-bit Mono runtime using SGEN GC and default BCL profile (net_4_x): + ```bash ./autogen.sh --prefix=$PREFIX --host=i686-w64-mingw32 --enable-msvc --disable-boehm make -j4 @@ -89,11 +91,11 @@ The following configure steps shows different supported Mono build configuration **NOTE**, 32-bit Mono runtime supports both SGEN and Boehm GC. Boehm GC is still available for legacy reasons but not supported on 64-bit Windows builds. It is recommended to use SGEN GC for both 32 and 64-bit Windows builds. -### Enable BTLS as cryptographic backend for Windows builds. +### Enable BTLS as cryptographic backend for Windows builds Mono on Windows supports BTLS library as an alternative cryptographic backend for SSL/TLS. It is not the default alternative and must be enabled to build and be used by Mono runtime. To enable BTLS, pass `--enable-btls` to the `autogen.sh` step above. -BTLS build will add a couple of additional prerequisites for Visual Studio builds. The easiest way to get additional needed packages is to install and use [Chocolatey](https://chocolatey.org/) package manager. See https://chocolatey.org/install for instructions on how to install Chocolatey package manager into the build system. +BTLS build will add a couple of additional prerequisites for Visual Studio builds. The easiest way to get additional needed packages is to install and use [Chocolatey](https://chocolatey.org/) package manager. See for instructions on how to install Chocolatey package manager into the build system. Once Chocolatey has been installed, add the following packages to the build system: @@ -111,7 +113,7 @@ choco install yasm Make sure they are all visible to the build environment used by Visual Studio (restart any command prompts or Visual Studio IDE's used in the build). -### Enable LLVM for Windows builds. +### Enable LLVM for Windows builds Mono on Windows supports LLVM in several different build combinations. When doing Windows cross compiler builds, host == Win32 but target != Win32, standard LLVM build instructions can be used. @@ -133,7 +135,7 @@ When set to a path pointing to a pre-build version of `llvm-config.exe`, specifi Additional prerequisites only applies when building LLVM as part of Visual Studio Mono runtime build. If using `--with-llvm` configuration option or MONO_EXTERNAL_LLVM_CONFIG MSBuild property, no additional prerequisites are needed. -LLVM build will add a couple of additional prerequisites for Visual Studio builds. The easiest way to get additional needed packages is to install and use [Chocolatey](https://chocolatey.org/) package manager. See https://chocolatey.org/install for instructions on how to install Chocolatey package manager into the build system. +LLVM build will add a couple of additional prerequisites for Visual Studio builds. The easiest way to get additional needed packages is to install and use [Chocolatey](https://chocolatey.org/) package manager. See for instructions on how to install Chocolatey package manager into the build system. Once Chocolatey has been installed, add the following packages to the build system: @@ -150,7 +152,7 @@ choco install ninja Make sure they are all visible to the build environment used by Visual Studio (restart any command prompts or Visual Studio IDE's used in the build). -### Use monolite instead of pre-installed Mono distribution. +### Use monolite instead of pre-installed Mono distribution If no Mono distribution is available, you can build using `monolite`. Just run the command below before running `make`: @@ -204,7 +206,7 @@ Example of a Visual Studio 2017 64-bit Mono runtime release build using sgen GC: msbuild.exe /p:PlatformToolset=v141 /p:Platform=x64 /p:Configuration=Release /p:MONO_TARGET_GC=sgen msvc/mono.sln ``` -There is also a build script that can be used to run `msbuild.exe` from a Visual Studio build environment, `msvc\run-msbuild.bat`. The script selects Visual Studio version toolchain based on `VisualStudioVersion` environment variable. +There is also a build script that can be used to run `msbuild.exe` from a Visual Studio build environment, `msvc\run-msbuild.bat`. The script selects Visual Studio version toolchain based on `VisualStudioVersion` environment variable. For Visual Studio 2015 64-bit Mono Runtime build: @@ -222,7 +224,7 @@ msvc\run-msbuild.bat "/p:Configuration=Release /p:Platform=x64 /p:MONO_TARGET_GC **NOTE**, while it is possible to run `msbuild.exe` from Cygwin environment it is not recommended since the build might pick up build tools and dependencies from Cygwin instead of Windows environment. There is however a build script `msvc/run-msbuild.sh` that can be called from Cygwin that will try to setup original Windows environment before running `msbuild.exe`. -### Visual Studio MSBuild build properties. +### Visual Studio MSBuild build properties Building Mono runtime using Visual Studio offers a number of additional options compared to regular `autogen.sh`configuration steps. These properties can be explicitly passed to MBuild or set in `mono.props` property file, read by Mono Visual Studio build. @@ -262,7 +264,7 @@ Mono runtime will link and include BTLS. Setting this value to true will also bu NOTE, since BTLS support is part of BCL build, just setting this when doing Mono runtime build will not include needed BTLS support in BCL build. It is recommended to use `--enable-btls` as part of configuration step since that will make sure BTLS support is included in both BCL as well as Mono runtime build. -### Configure `make` to use Visual Studio build Mono runtime. +### Configure `make` to use Visual Studio build Mono runtime For make to use Visual Studio build Mono runtime when building BCL and test, set `MONO_EXECUTABLE` environment variable to Visual Studio build Mono runtime. Switch to the Cygwin shell previously used and run: @@ -272,7 +274,7 @@ export MONO_EXECUTABLE=/cygdrive/c/mono-source-location/msvc/build/sgen/x64/bin/ **NOTE**, above path will change depending on source location, build location, 32/64-bit build configuration and used GC. The example above uses the default build location for a 64-bit release build Mono runtime configured to use SGEN GC. -## Build Mono mingw runtime, BCL and Tests. +## Build Mono mingw runtime, BCL and Tests Switch to the Cygwin shell previously used and run: @@ -299,7 +301,7 @@ If you use an earlier Windows versions, you need to run the build as administrat ## Run all tests -Make sure `MONO_EXECUTABLE` has been setup to use Visual Studio build Mono runtime, see above for instructions. For all tests to run and pass, the Cygwin shell will need elevated permissions. Without additional permissions, some test failures will be identified. +Make sure `MONO_EXECUTABLE` has been setup to use Visual Studio build Mono runtime, see above for instructions. For all tests to run and pass, the Cygwin shell will need elevated permissions. Without additional permissions, some test failures will be identified. ```bash make check diff --git a/docs/debug+profile/debug/lldb-source-map.md b/docs/debug+profile/debug/lldb-source-map.md index 6d0e5a982..a21ba09f8 100644 --- a/docs/debug+profile/debug/lldb-source-map.md +++ b/docs/debug+profile/debug/lldb-source-map.md @@ -17,34 +17,38 @@ Let's say we're interesed in Mono 6.0.0.x (2019-02) (see: [Mono source versionin 2. Check out the Mono source code somewhere in your home directory, for example `/Users/work/2019-02/mono` 3. Start debugging `lldb mono example.exe` 4. Lookup a mono symbol to find out where the source code was when Jenkins built the package - ``` + + ```bash (lldb) image lookup -vn mini_init 1 match found in /Library/Frameworks/Mono.framework/Versions/Current/Commands/mono: ... CompileUnit: id = {0xffffffff00084fd3}, file = "/Users/builder/jenkins/workspace/build-package-osx-mono/2019-02/external/bockbuild/builds/mono-x64/mono/mini/mini-runtime.c", language = "c99" ... ``` + 5. Set up a "source map" telling LLDB where the code really is - ``` + + ```bash (lldb) settings set -- target.source-map "/Users/builder/jenkins/workspace/build-package-osx-mono/2019-02/external/bockbuild/builds/mono-x64" "/Users/work/2019-02/mono" ``` + 6. Set a breakpoint and start running - ``` + ```bash (lldb) b mini_init (lldb) r * thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1 frame #0: 0x0000000100011bb8 mono`mini_init(filename="foo.exe", runtime_version=0x0000000000000000) at mini-runtime.c:4134:2 [opt] - 4131 MonoDomain * - 4132 mini_init (const char *filename, const char *runtime_version) - 4133 { - -> 4134 ERROR_DECL (error); - 4135 MonoDomain *domain; - 4136 MonoRuntimeCallbacks callbacks; - 4137 MonoThreadInfoRuntimeCallbacks ticallbacks; + 4131 MonoDomain * + 4132 mini_init (const char *filename, const char *runtime_version) + 4133 { + -> 4134 ERROR_DECL (error); + 4135 MonoDomain *domain; + 4136 MonoRuntimeCallbacks callbacks; + 4137 MonoThreadInfoRuntimeCallbacks ticallbacks; Target 0: (mono) stopped. ``` - -### Debugging more than one piece of code. + +### Debugging more than one piece of code To add symbols for some other shared library, use `settings append -- target.source-map ` to add a second mapping, instead of `settings set`. diff --git a/docs/debug+profile/debug/telemetry.md b/docs/debug+profile/debug/telemetry.md index 0c0064984..cdd2f531f 100644 --- a/docs/debug+profile/debug/telemetry.md +++ b/docs/debug+profile/debug/telemetry.md @@ -8,28 +8,28 @@ redirect_from: Use Cases ---------------------------- -Getting users to report bugs and crashes is a difficult problem. +Getting users to report bugs and crashes is a difficult problem. It's important to keep the barrier to entry low, while still ensuring that bug filers are providing actionable information. Often a filer does not provide enough information, requiring many messages be sent back and forth before the developer can begin working on the bug. Users often lose interest a few days or weeks after filing the bug, leaving only an ambiguous description of bug reproduction and no stack traces, logs, or executable reproductions. Often many users report the same bug in the same incomplete way. Other crashes are hidden -due to automatic recovery, and are never reported. +due to automatic recovery, and are never reported. What if that initial exchange could be so simple and information-rich that bugs could be filed in an automatic manner? What if two identical crashes could be automatically deduplicated? What if you could identify platform attributes that seem to accompany bugs using statistics, rather than relying on bug reporters to describe it? Such telemetry systems are very attractive for clear reasons, but they are often tied to a single project or a single company. -They're often custom-made solutions that can't be reused by the community. Heavyweight bug collection and always-on reporting -that sends enormous amounts of data back to this single source is not only inconvenient. In the modern world, it can be illegal. -Legislation like the GDPR increasingly regulates what can be sent. +They're often custom-made solutions that can't be reused by the community. Heavyweight bug collection and always-on reporting +that sends enormous amounts of data back to this single source is not only inconvenient. In the modern world, it can be illegal. +Legislation like the GDPR increasingly regulates what can be sent. Mono has therefore created a reusable, privacy-preserving crash reporting system. For faults that are due to unmanaged exceptions, the system will work out of the box. For managed unhandled exceptions, it takes just a bit of configuration. By opting to use this system to report all managed and native parts of their application, someone shipping code using Mono can leverage this crash reporting -infrastructure. +infrastructure. Whether you're shipping a commercial C# application on OSX, embedding Mono into your application, or running a C#-heavy linux desktop suite, this crash reporting system aspires to have something to offer to you. @@ -38,12 +38,12 @@ Normal Crash Reporting ---------------------------- We have a lot of options described in future sections, but it's worth remembering that the critical path of this code -is in response to Mono crashing. This works by default, nothing needs to be enabled to get a crash file when Mono -has an unmanaged crash occur. +is in response to Mono crashing. This works by default, nothing needs to be enabled to get a crash file when Mono +has an unmanaged crash occur. (Note that crash reporting is not enabled for all platforms. Windows and mobile are excluded, for instance.) When that happens, the OS has sent Mono a native signal indicating a failed assertion, -memory protection fault, or other illegal operation. When the runtime receives this signal, it +memory protection fault, or other illegal operation. When the runtime receives this signal, it will perform a global Crash Reporting runtime state dump. A global state dump that has been triggered by an unmanaged crash does the following steps: @@ -61,13 +61,12 @@ Mono, and walks their stack. Before allowing these other threads to resume, the versioned JSON in a specialized runtime format. This blob is written to disk with a filename that includes a hash of the stacktrace. - Privacy and the GDPR ----------------------------- +-------------------- It's vital in the modern era to not violate users' trust whenever their data comes into your possession. The GDPR has a strict definition of what constitutes private or identifying information. Our dump format is -specially designed to only collect information that we know is alright to collect. +specially designed to only collect information that we know is alright to collect. We are careful to never include the data from the running program in the application, only references to information in the program itself. For instance, we describe the program version, amount of memory in use, @@ -75,21 +74,20 @@ and the stack traces for every running mono thread. These stack traces describe foreign keys that can be used to determine which function is at which position in the frame. If a user's program happens to have frames above ours (let's say they're using our library), -then we won't have the information required to turn the primary keys in their code into names to methods and +then we won't have the information required to turn the primary keys in their code into names to methods and classes. This separation of symbolification preserves privacy. This ensures that users know they can feel comfortable distributing crash files without worrying that their secrets will be exposed. - -ICalls For Crash Reporting ----------------------------- +ICalls For Crash Reporting +-------------------------- ### Producing Crash Files There are a few ways to get a telemetry-ready file without having to kill the runtime: -All of the below ICalls produce a Tuple containing a string, a ulong, and another ulong. +All of the below ICalls produce a Tuple containing a string, a ulong, and another ulong. The string contains the textual content of the runtime dump that was collected. It is a versioned blob of JSON that fits our particular runtime format. We describe in a section later in this document @@ -99,22 +97,22 @@ We also have two ulongs which are crash hashes. These are made by hashing attributes of the managed stack of the thread that triggered the dump. The first one returned is a "portable hash" that does not contain method offsets or other things that are highly likely to change between versions of an application. The -second one is an "unportable hash" that contains these attributes. +second one is an "unportable hash" that contains these attributes. These hashes can be used to deduplicate stacktraces. It's recommended not to simply discard duplicates, as there are logged details of the application context that may be useful for isolating things required to reproduce a crash. Our Crash Reporting support is behind a number of private, reflection-only methods from the -Mono.Runtime namespace. +Mono.Runtime namespace. You will want to use an invocation resembling the below example to make an ICall: -``` - var monoType = Type.GetType ("Mono.Runtime", false); - var send = monoType.GetMethod(iCallName, BindingFlags.NonPublic | BindingFlags.Static); - var send_params = new object[] {exc}; - send.Invoke(null, send_params); +```csharp +var monoType = Type.GetType ("Mono.Runtime", false); +var send = monoType.GetMethod(iCallName, BindingFlags.NonPublic | BindingFlags.Static); +var send_params = new object[] {exc}; +send.Invoke(null, send_params); ``` The variable above called "iCallName" should be replaced with the name of one of the ICalls mentioned @@ -122,28 +120,28 @@ below. ### DumpStateTotal -``` - static Tuple DumpStateTotal () +```csharp +static Tuple DumpStateTotal () ``` The first one here dumps the entire runtime. It has to stop other threads, and so relies on the thread halting machinery used during unmanaged crashes that we described above. This thread suspension machinery relies on OS signals, which can on rare occasions interfere -with correct functioning of native threads associated with the crashing runtime. +with correct functioning of native threads associated with the crashing runtime. This is not to say that this ICall is dangerous for most applications. This ICall is tested under situations where there are many concurrent global dump requests being made at once. Nevertheless, there remains a risk that native code which is low level enough will be able to observe an unexpected signal. Internal bugs can be exposed by unexpected platform quirks. The thread cooperation has an observable performance cost. Noticeably, it will render all threads -unresponsive for a short, limited duration. It is not appropriate to use this ICall in a context -where one expects it to be called many times per second. +unresponsive for a short, limited duration. It is not appropriate to use this ICall in a context +where one expects it to be called many times per second. ### DumpStateSingle -``` - static Tuple DumpStateSingle () +```csharp +static Tuple DumpStateSingle () ``` This ICall will only get the stack of the calling thread. It will be much faster, and doesn't @@ -152,8 +150,8 @@ thread needs to be dumped, consider using this one instead. ### ExceptionToState -``` - static Tuple ExceptionToState (Exception exc) +```csharp +static Tuple ExceptionToState (Exception exc) ``` The last option requires no stack walking. When a runtime has a managed exception that it would like to @@ -161,10 +159,10 @@ send to telemetry, it can convert it into a dump file. ### Native Crash Reporting Senders -``` - static void SendMicrosoftTelemetry (string payload_str, ulong portable_hash, ulong unportable_hash) +```csharp +static void SendMicrosoftTelemetry (string payload_str, ulong portable_hash, ulong unportable_hash) - static void WriteStateToFile (Exception exc) +static void WriteStateToFile (Exception exc) ``` The above are two examples of telemetry serializers or senders you'll find if you examine Mono.Runtime. @@ -177,41 +175,38 @@ someone in the community. It stores the managed exception as a text file on the encodes the hash. This is a convenient way to serialize unhandled managed exceptions. It will use `ExceptionToState` to produce a crash dump to write to a file. We write the file to the working directory with a specially-formatted name. -``` - AppDomain.CurrentDomain.UnhandledException += new UnhandledExceptionEventHandler(HandleException); - } - - public static void HandleException (object sender, UnhandledExceptionEventArgs e) - { - var exc = e.ExceptionObject as Exception; - - var monoType = Type.GetType ("Mono.Runtime", false); - var send = monoType.GetMethod("WriteStateToFile", BindingFlags.NonPublic | BindingFlags.Static); - var send_params = new object[] {exc}; - send.Invoke(null, send_params); - } -``` +```csharp +AppDomain.CurrentDomain.UnhandledException += new UnhandledExceptionEventHandler(HandleException); +public static void HandleException (object sender, UnhandledExceptionEventArgs e) +{ + var exc = e.ExceptionObject as Exception; + + var monoType = Type.GetType ("Mono.Runtime", false); + var send = monoType.GetMethod("WriteStateToFile", BindingFlags.NonPublic | BindingFlags.Static); + var send_params = new object[] {exc}; + send.Invoke(null, send_params); +} +``` ### Configuration -``` - static void RegisterReportingForNativeLib (string modulePathSuffix_str, string moduleName_str) +```csharp +static void RegisterReportingForNativeLib (string modulePathSuffix_str, string moduleName_str) ``` When working with native libraries other than Mono that one wants crash reporting for, it's important to correctly register the library. The first argument to this ICall is some unique suffix of the path to the native library in question. This is a platform-dependent and application-dependent string. -This is being compared against the value returned from dladdr for the file path. It's recommended to double +This is being compared against the value returned from dladdr for the file path. It's recommended to double check that the string returned from dladdr matches what's expected. Mono gets symbols by default. Any frames that point to functions in other native libraries will not appear in a dump by default. There will just be a placeholder message that the frame had an unregistered method. Upon registering the -native library, the frame will be reported to have the relevant module, function address, and offset. - +native library, the frame will be reported to have the relevant module, function address, and offset. -Crash Reporting Via Debugger +Crash Reporting Via Debugger ---------------------------- ### Interactively @@ -219,7 +214,7 @@ Crash Reporting Via Debugger When attached with a debugger, VM termination results in a disconnect. There are many reasons why this can happen, each of which is explained differently by the debugger client. When the VM disconnects because it has an unhandled native exception, a CrashEvent is sent to the debugger client. It will display that the cause of VM termination is due to a crash. It may display -the crash JSON directly, to enable easy bug filing. +the crash JSON directly, to enable easy bug filing. Copying and pasting the text and the hash enables someone to query a database of existing crashes and to see if this hash has been seen before. Knowing that one just reproduced a specific bug can be very useful for a developer. @@ -249,7 +244,7 @@ and the offset of the instruction in the function (`native_offset`). Examine the below sample frame from the crash file: -``` +```json { "native_address" : "0x1003a6340", "native_offset" : "0x00046", @@ -260,7 +255,7 @@ Examine the below sample frame from the crash file: We can search for the address of the function offset in the output of any symbolication tool when applied to the native library. - ``` + ```bash $ nm mini/mono-sgen | grep '1003a6340' 00000001003a6340 t _mono_runtime_run_main_checked @@ -271,7 +266,7 @@ If it's inconvenient to have to have the binary in question on hand for symbolic precompute a small database. The data can be found using the below command. Grepping for function addresses through the output of this command is also a valid way to symbolicate in a non-automated manner. -``` +```bash $ nm mini/mono-sgen | grep ' t ' | sort -n 00000001000a4e90 t _alloc_ireg @@ -288,7 +283,7 @@ provide that information. The gdb command `p/a $native_address + $native_offset` ### Managed Stack Frames -The crash format gives a managed frame a GUID to their assembly, a token to the method, and an IL offset. From there, a line number in a source file can be retrieved by the symbolicator using Mono.Cecil. +The crash format gives a managed frame a GUID to their assembly, a token to the method, and an IL offset. From there, a line number in a source file can be retrieved by the symbolicator using Mono.Cecil. ### Uploader Examples (Sentry) diff --git a/docs/getting-started/install/linux/index.md b/docs/getting-started/install/linux/index.md index e30d43e19..87b1c80d2 100644 --- a/docs/getting-started/install/linux/index.md +++ b/docs/getting-started/install/linux/index.md @@ -16,7 +16,9 @@ If for some reason you want to pin an older version of Mono rather than updating _Note:_ you'll get a warning similar to this one when running `apt update`, it is harmless and can be ignored: -> W: Conflicting distribution: https://download.mono-project.com stable-jessie/snapshots/3.10.0.160 InRelease (expected stable-jessie/snapshots but got jessie) +```bash +W: Conflicting distribution: https://download.mono-project.com stable-jessie/snapshots/3.10.0.160 InRelease (expected stable-jessie/snapshots but got jessie) +``` These snapshots will cease receiving updates as soon as the next major Mono version gets uploaded - for example, as soon as Mono 3.12 gets uploaded, 3.10 will never receive updates. diff --git a/docs/getting-started/mono-basics.md b/docs/getting-started/mono-basics.md index bb2508bbe..a54d60942 100644 --- a/docs/getting-started/mono-basics.md +++ b/docs/getting-started/mono-basics.md @@ -13,10 +13,9 @@ To test the most basic functionality available, copy the following code into a f ``` csharp using System; -  + public class HelloWorld { - public static void Main(string[] args) { Console.WriteLine ("Hello Mono World"); @@ -36,7 +35,7 @@ The compiler will create "hello.exe", which you can run using: ``` bash mono hello.exe -``` +``` The program should run and output: diff --git a/docs/gui/gtksharp/beginners-guide.md b/docs/gui/gtksharp/beginners-guide.md index 9addbe1fe..8a55e6235 100644 --- a/docs/gui/gtksharp/beginners-guide.md +++ b/docs/gui/gtksharp/beginners-guide.md @@ -156,13 +156,13 @@ I'm assuming that you are familiar with C#, so most of this will look normal. We ``` csharp using System; using Gtk; -  + public class GtkHelloWorld { -  + public static void Main() { Console.WriteLine("HelloWorld"); } -  + } ``` @@ -179,9 +179,9 @@ When the size of your projects grows, you may start using multiple ".cs" files t MCS does all of the behind the scenes work to compile everything in the right order, so it can be in any order, like: mcs -pkg:gtk-sharp-2.0 helloword2.cs helloworld1.cs helloworld3.cs - + If you were so inclined, you can also write all of this in a Bash script so you don't have to run the same command repeatedly and can just make edits as needed. - + Step 4: Adding the GUI ---------------------- @@ -190,26 +190,26 @@ Now lets jump back to our code. Go ahead and remove the "Console.WriteLine" stat ``` csharp using System; using Gtk; -  + public class GtkHelloWorld { -  + public static void Main() { Application.Init(); -  + //Create the Window Window myWin = new Window("My first GTK# Application! "); myWin.Resize(200,200); -  + //Create a label and put some text in it. Label myLabel = new Label(); myLabel.Text = "Hello World!!!!"; -  + //Add the label to the form myWin.Add(myLabel); -  + //Show Everything myWin.ShowAll(); -  + Application.Run(); } } @@ -332,7 +332,7 @@ using Gdk; if (args.Event.Type == EventType.TwoButtonPress) { ... } -  + // the left button was used if (args.Event.Button == 1) { ... @@ -361,9 +361,9 @@ file: gui.glade ``` xml -  + -  + True Glade Window @@ -380,7 +380,7 @@ file: gui.glade GDK_WINDOW_TYPE_HINT_NORMAL GDK_GRAVITY_NORTH_WEST True -  + True @@ -389,7 +389,7 @@ file: gui.glade GTK_POLICY_ALWAYS GTK_SHADOW_IN GTK_CORNER_TOP_LEFT -  + True @@ -397,7 +397,7 @@ file: gui.glade 400 0 0 400 10 212.4 236 0 0 400 10 212.4 236 -  + 38 @@ -423,7 +423,7 @@ file: gui.glade 88 -  + 60 @@ -445,7 +445,7 @@ file: gui.glade -  + ``` @@ -471,11 +471,11 @@ public class GladeApp { new GladeApp (args); } -  + public GladeApp (string[] args) { Application.Init(); -  + Glade.XML gxml = new Glade.XML (null, "gui.glade", "window1", null); gxml.Autoconnect (this); Application.Run(); @@ -526,19 +526,19 @@ public class GladeApp { new GladeApp (args); } -  + public GladeApp (string[] args) { Application.Init(); -  + Glade.XML gxml = new Glade.XML (null, "gui.glade", "window1", null); gxml.Autoconnect (this); Application.Run(); } -  + [Widget] Button button1; -  + [Widget] Label label1; } @@ -559,25 +559,25 @@ public class GladeApp { new GladeApp (args); } -  + public GladeApp (string[] args) { Application.Init(); -  + Glade.XML gxml = new Glade.XML (null, "gui.glade", "window1", null); gxml.Autoconnect (this); -  + button1.Clicked += OnPressButtonEvent; -  + Application.Run(); } -  + [Glade.Widget] Button button1; -  + [Glade.Widget] Label label1; -  + public void OnPressButtonEvent( object o, EventArgs e) { Console.WriteLine("Button press");