diff --git a/documentation/content/en/articles/contributing/_index.adoc b/documentation/content/en/articles/contributing/_index.adoc index 63ebc42b39..cd889a2361 100644 --- a/documentation/content/en/articles/contributing/_index.adoc +++ b/documentation/content/en/articles/contributing/_index.adoc @@ -1,594 +1,575 @@ --- title: Contributing to FreeBSD authors: - author: Jordan Hubbard - author: Sam Lawrance - author: Mark Linimon description: How to contribute to the FreeBSD Project trademarks: ["freebsd", "ieee", "general"] weight: 15 tags: ["Contributing", "FreeBSD", "Non-Programmer Tasks", "Programmer Tasks"] --- = Contributing to FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :images-path: articles/contributing/ ifdef::env-beastie[] ifdef::backend-html5[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] :imagesdir: ../../../images/{images-path} endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [.abstract-title] Abstract This article describes the different ways in which an individual or organization may contribute to the FreeBSD Project. ''' toc::[] So you want to contribute to FreeBSD? That is great! FreeBSD _relies_ on the contributions of its user base to survive. Your contributions are not only appreciated, they are vital to FreeBSD's continued growth. A large and growing number of international contributors, of greatly varying ages and areas of technical expertise, develop FreeBSD. There is always more work to be done than there are people available to do it, and more help is always appreciated. As a volunteer, what you do is limited only by what you want to do. However, we do ask that you are aware of what other members of the FreeBSD community will expect of you. You may want to take this into account before deciding to volunteer. The FreeBSD project is responsible for an entire operating system environment, rather than just a kernel or a few scattered utilities. As such, our [.filename]#TODO# lists span a very wide range of tasks: from documentation, beta testing and presentation, to the system installer and highly specialized types of kernel development. People of any skill level, in almost any area, can almost certainly help the project. Commercial entities engaged in FreeBSD-related enterprises are also encouraged to contact us. Do you need a special extension to make your product work? You will find us receptive to your requests, given that they are not too outlandish. Are you working on a value-added product? Please let us know! We may be able to work cooperatively on some aspect of it. The free software world is challenging many existing assumptions about how software is developed, sold, and maintained, and we urge you to at least give it a second look. [[contrib-what]] == What Is Needed The following list of tasks and sub-projects represents something of an amalgam of various [.filename]#TODO# lists and user requests. [[non-programmer-tasks]] === Ongoing Non-Programmer Tasks Many people who are involved in FreeBSD are not programmers. The Project includes documentation writers, Web designers, and support people. All that these people need to contribute is an investment of time and a willingness to learn. . Read through the FAQ and Handbook periodically. If anything is poorly explained, ambiguous, out of date or incorrect, let us know. Even better, send us a fix (AsciiDoc is not difficult to learn, but there is no objection to plain text submissions). . Help translate FreeBSD documentation into your native language. If documentation already exists for your language, you can help translate additional documents or verify that the translations are up-to-date and correct. First take a look at the extref:{fdp-primer}[Translations FAQ, translations] in the FreeBSD Documentation Project Primer. You are not committing yourself to translating every single FreeBSD document by doing this - as a volunteer, you can do as much or as little translation as you desire. Once someone begins translating, others almost always join the effort. If you only have the time or energy to translate one part of the documentation, please translate the installation instructions. . Read the {freebsd-questions} occasionally (or even regularly). It can be very satisfying to share your expertise and help people solve their problems; sometimes you may even learn something new yourself! These forums can also be a source of ideas for things to improve upon. [[ongoing-programmer-tasks]] === Ongoing Programmer Tasks Most of the tasks listed here may require a considerable investment of time, an in-depth knowledge of the FreeBSD kernel, or both. However, there are also many useful tasks which are suitable for "weekend hackers". . If you run FreeBSD-CURRENT and have a good Internet connection, there is a machine `current.FreeBSD.org` which builds a full release once a day-every now and again, try to install the latest release from it and report any failures in the process. . Read the {freebsd-bugs}. There may be a problem you can comment constructively on or with patches you can test. Or you could even try to fix one of the problems yourself. . If you know of any bug fixes which have been successfully applied to -CURRENT but have not been merged into -STABLE after a decent interval (normally a couple of weeks), send the committer a polite reminder. . Move contributed software to [.filename]#src/contrib# in the source tree. . Make sure code in [.filename]#src/contrib# is up to date. . Build the source tree (or just part of it) with extra warnings enabled and clean up the warnings. A list of build warnings can also be found from our https://ci.freebsd.org[CI] by selecting a build and checking "LLVM/Clang Warnings". . Fix warnings for ports which do deprecated things like using `gets()` or including [.filename]#malloc.h#. . If you have contributed any ports and you had to make FreeBSD-specific changes, send your patches back to the original authors (this will make your life easier when they bring out the next version). . Get copies of formal standards like POSIX(R). Compare FreeBSD's behavior to that required by the standard. If the behavior differs, particularly in subtle or obscure corners of the specification, send in a PR about it. If you are able, figure out how to fix it and include a patch in the PR. If you think the standard is wrong, ask the standards body to consider the question. . Suggest further tasks for this list! === Work through the PR Database The https://bugs.FreeBSD.org/search/[FreeBSD PR list] shows all the current active problem reports and requests for enhancement that have been submitted by FreeBSD users. The PR database includes both programmer and non-programmer tasks. Look through the open PRs, and see if anything there takes your interest. Some of these might be very simple tasks that just need an extra pair of eyes to look over them and confirm that the fix in the PR is a good one. Others might be much more complex, or might not even have a fix included at all. Start with the PRs that have not been assigned to anyone else. If a PR is assigned to someone else, but it looks like something you can handle, email the person it is assigned to and ask if you can work on it-they might already have a patch ready to be tested, or further ideas that you can discuss with them. === Ongoing Ports Tasks The Ports Collection is a perpetual work in progress. We want to provide our users with an easy to use, up to date, high quality repository of third party software. We need people to donate some of their time and effort to help us achieve this goal. Anyone can get involved, and there are lots of different ways to do so. Contributing to ports is an excellent way to help "give back" something to the project. Whether you are looking for an ongoing role, or a fun challenge for a rainy day, we would love to have your help! There are a number of easy ways you can contribute to keeping the ports tree up to date and in good working order: * Find some cool or useful software and extref:{porters-handbook}[create a port] for it. * There are a large number of ports that have no maintainer. Become a maintainer and <>. * If you have created or adopted a port, be aware of <>. * When you are looking for a quick challenge you could <>. === Pick one of the items from the Ideas page The https://wiki.freebsd.org/IdeasPage[FreeBSD list of projects and ideas for volunteers] is also available for people willing to contribute to the FreeBSD project. The list is being regularly updated and contains items for both programmers and non-programmers with information about each project. [[contrib-how]] == How to Contribute Contributions to the system generally fall into one or more of the following 5 categories: [[contrib-general]] === Bug Reports and General Commentary An idea or suggestion of _general_ technical interest should be mailed to the {freebsd-hackers}. Likewise, people with an interest in such things (and a tolerance for a _high_ volume of mail!) may subscribe to the {freebsd-hackers}. See extref:{handbook}[The FreeBSD Handbook, eresources-mail] for more information about this and other mailing lists. If you find a bug or are submitting a specific change, please report it using the https://bugs.FreeBSD.org/submit/[bug submission form]. Try to fill-in each field of the bug report. Unless they exceed 65KB, include any patches directly in the report. If the patch is suitable to be applied to the source tree put `[PATCH]` in the synopsis of the report. When including patches, _do not_ use cut-and-paste because cut-and-paste turns tabs into spaces and makes them unusable. When patches are a lot larger than 20KB, consider compressing them (eg. with man:gzip[1] or man:bzip2[1]) prior to uploading them. After filing a report, you should receive confirmation along with a tracking number. Keep this tracking number so that you can update us with details about the problem. See also extref:{problem-reports}[this article] on how to write good problem reports. === Changes to the Documentation Changes to the documentation are overseen by the {freebsd-doc}. Please look at the extref:{fdp-primer}[FreeBSD Documentation Project Primer] for complete instructions. Send submissions and changes (even small ones are welcome!) using the same method as any other bug report. === Changes to Existing Source Code An addition or change to the existing source code is a somewhat trickier affair and depends a lot on how far out of date you are with the current state of FreeBSD development. There is a special on-going release of FreeBSD known as "FreeBSD-CURRENT" which is made available in a variety of ways for the convenience of developers working actively on the system. See extref:{handbook}[The FreeBSD Handbook, current-stable] for more information about getting and using FreeBSD-CURRENT. Working from older sources unfortunately means that your changes may sometimes be too obsolete or too divergent for easy re-integration into FreeBSD. Chances of this can be minimized somewhat by subscribing to the {freebsd-announce} and the {freebsd-current} lists, where discussions on the current state of the system take place. Assuming that you can manage to secure fairly up-to-date sources to base your changes on, the next step is to produce a set of diffs to send to the FreeBSD maintainers. This is done with the man:diff[1] command. The preferred man:diff[1] format for submitting patches is the unified output format generated by `diff -u`. [source,shell] .... % diff -u oldfile newfile .... or [source,shell] .... % diff -u -r -N olddir newdir .... would generate a set of unified diffs for the given source file or directory hierarchy. See man:diff[1] for more information. Once you have a set of diffs (which you may test with the man:patch[1] command), you should submit them for inclusion with FreeBSD as a bug report. _Do not_ just send the diffs to the {freebsd-hackers} or they will get lost! We greatly appreciate your submission (this is a volunteer project!); because we are busy, we may not be able to address it immediately, but it will remain in the PR database until we do. Indicate your submission by including `[PATCH]` in the synopsis of the report. If you feel it appropriate (e.g. you have added, deleted, or renamed files), bundle your changes into a `tar` file. Archives created with man:shar[1] are also welcome. If your change is of a potentially sensitive nature, such as if you are unsure of copyright issues governing its further distribution then you should send it to {core-email} directly rather than submitting as a bug report. The {core-email} reaches a much smaller group of people who do much of the day-to-day work on FreeBSD. Note that this group is also _very busy_ and so you should only send mail to them where it is truly necessary. Please refer to man:intro[9] and man:style[9] for some information on coding style. We would appreciate it if you were at least aware of this information before submitting code. === New Code or Major Value-Added Packages In the case of a significant contribution of a large body work, or the addition of an important new feature to FreeBSD, it becomes almost always necessary to either send changes as tar files or upload them to a web or FTP site for other people to access. If you do not have access to a web or FTP site, ask on an appropriate FreeBSD mailing list for someone to host the changes for you. When working with large amounts of code, the touchy subject of copyrights also invariably comes up. FreeBSD prefers free software licenses such as BSD or ISC. Copyleft licenses such as GPLv2 are sometimes permitted. The complete listing can be found on the link:https://www.FreeBSD.org/internal/software-license/[core team licensing policy] page. === Money or Hardware We are always very happy to accept donations to further the cause of the FreeBSD Project and, in a volunteer effort like ours, a little can go a long way! Donations of hardware are also very important to expanding our list of supported peripherals since we generally lack the funds to buy such items ourselves. [[donations]] ==== Donating Funds The https://www.freebsdfoundation.org[FreeBSD Foundation] is a non-profit, tax-exempt foundation established to further the goals of the FreeBSD Project. As a 501(c)3 entity, the Foundation is generally exempt from US federal income tax as well as Colorado State income tax. Donations to a tax-exempt entity are often deductible from taxable federal income. Donations may be sent in check form to: [.address] **** The FreeBSD Foundation + 3980 Broadway Street + STE #103-107 + Boulder CO 80304 + USA **** The FreeBSD Foundation is also able to accept https://www.freebsdfoundation.org/donate/[online donations] through various payment options. More information about the FreeBSD Foundation can be found in https://people.FreeBSD.org/~jdp/foundation/announcement.html[The FreeBSD Foundation -- an Introduction]. To contact the Foundation by email, write to mailto:info@FreeBSDFoundation.org[info@FreeBSDFoundation.org]. ==== Donating Hardware The FreeBSD Project happily accepts donations of hardware that it can find good use for. If you are interested in donating hardware, please contact the link:https://www.FreeBSD.org/donations/[Donations Liaison Office]. [[ports-contributing]] == Contributing to ports [[adopt-port]] === Adopting an unmaintained port ==== Choosing an unmaintained port Taking over maintainership of ports that are unmaintained is a great way to get involved. Unmaintained ports are only updated and fixed when somebody volunteers to work on them. There are a large number of unmaintained ports. It is a good idea to start with adopting a port that you use regularly. Unmaintained ports have their `MAINTAINER` set to `ports@FreeBSD.org`. -A list of unmaintained ports and their current errors and problem reports can be seen at the http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org[FreeBSD Ports Monitoring System]. +Many unmaintained ports can have pending updates, this can be seen at the https://portscout.freebsd.org/ports@freebsd.org.html[FreeBSD Ports distfile scanner]. On https://portsfallout.com/fallout?port=&maintainer=ports%40FreeBSD.org[PortsFallout] can be seen a list of unmaintained ports with errors. -Many unmaintained ports can have pending updates, this can be seen at the https://portscout.freebsd.org/ports@freebsd.org.html[FreeBSD Ports distfile scanner]. - Some ports affect a large number of others due to dependencies and slave port relationships. Generally, we want people to have some experience before they maintain such ports. You can find out whether or not a port has dependencies or slave ports by looking at a master index of ports called [.filename]#INDEX#. (The name of the file varies by release of FreeBSD; for instance, [.filename]#INDEX-8#.) Some ports have conditional dependencies that are not included in a default [.filename]#INDEX# build. We expect you to be able to recognize such ports by looking through other ports' [.filename]#Makefile#'s. -[NOTE] -====== -The FreeBSD Ports Monitoring System (portsmon) is currently not working due to latest Python updates. -====== - ==== How to adopt the port First make sure you understand your <>. Also read the extref:{porters-handbook}[Porter's Handbook]. _Please do not commit yourself to more than you feel you can comfortably handle._ You may request maintainership of any unmaintained port as soon as you wish. Simply set `MAINTAINER` to your own email address and send a PR (Problem Report) with the change. If the port has build errors or needs updating, you may wish to include any other changes in the same PR. This will help because many committers are less willing to assign maintainership to someone who does not have a known track record with FreeBSD. Submitting PRs that fix build errors or update ports are the best ways to establish one. File your PR with category `ports` and class `change-request`. A committer will examine your PR, commit the changes, and finally close the PR. Sometimes this process can take a little while (committers are volunteers, too :). [[maintain-port]] === The challenge for port maintainers This section will give you an idea of why ports need to be maintained and outline the responsibilities of a port maintainer. [[why-maintenance]] ==== Why ports require maintenance Creating a port is a once-off task. Ensuring that a port is up to date and continues to build and run requires an ongoing maintenance effort. Maintainers are the people who dedicate some of their time to meeting these goals. The foremost reason ports need maintenance is to bring the latest and greatest in third party software to the FreeBSD community. An additional challenge is to keep individual ports working within the Ports Collection framework as it evolves. As a maintainer, you will need to manage the following challenges: * *New software versions and updates.* New versions and updates of existing ported software become available all the time, and these need to be incorporated into the Ports Collection in order to provide up-to-date software. * *Changes to dependencies.* If significant changes are made to the dependencies of your port, it may need to be updated so that it will continue to work correctly. * *Changes affecting dependent ports.* If other ports depend on a port that you maintain, changes to your port may require coordination with other maintainers. * *Interaction with other users, maintainers and developers.* Part of being a maintainer is taking on a support role. You are not expected to provide general support (but we welcome it if you choose to do so). What you should provide is a point of coordination for FreeBSD-specific issues regarding your ports. * *Bug hunting.* A port may be affected by bugs which are specific to FreeBSD. You will need to investigate, find, and fix these bugs when they are reported. Thoroughly testing a port to identify problems before they make their way into the Ports Collection is even better. * *Changes to ports infrastructure and policy.* Occasionally the systems that are used to build ports and packages are updated or a new recommendation affecting the infrastructure is made. You should be aware of these changes in case your ports are affected and require updating. * *Changes to the base system.* FreeBSD is under constant development. Changes to software, libraries, the kernel or even policy changes can cause flow-on change requirements to ports. ==== Maintainer responsibilities ===== Keep your ports up to date This section outlines the process to follow to keep your ports up to date. This is an overview. More information about upgrading a port is available in the extref:{porters-handbook}[Porter's Handbook]. [.procedure] ==== . Watch for updates + Monitor the upstream vendor for new versions, updates and security fixes for the software. Announcement mailing lists or news web pages are useful for doing this. Sometimes users will contact you and ask when your port will be updated. If you are busy with other things or for any reason just cannot update it at the moment, ask if they will help you by submitting an update. + You may also receive automated email from the `FreeBSD Ports Version Check` informing you that a newer version of your port's distfile is available. More information about that system (including how to stop future emails) will be provided in the message. . Incorporate changes + When they become available, incorporate the changes into the port. You need to be able to generate a patch between the original port and your updated port. . Review and test + Thoroughly review and test your changes: ** Build, install and test your port on as many platforms and architectures as you can. It is common for a port to work on one branch or platform and fail on another. ** Make sure your port's dependencies are complete. The recommended way of doing this is by installing your own ports tinderbox. See <> for more information. ** Check that the packing list is up to date. This involves adding in any new files and directories and removing unused entries. ** Verify your port using man:portlint[1] as a guide. See <> for important information about using portlint. ** Consider whether changes to your port might cause any other ports to break. If this is the case, coordinate the changes with the maintainers of those ports. This is especially important if your update changes the shared library version; in this case, at the very least, the dependent ports will need to get a `PORTREVISION` bump so that they will automatically be upgraded by automated tools such as portmaster or man:portupgrade[1]. . Submit changes + Send your update by submitting a PR with an explanation of the changes and a patch containing the differences between the original port and the updated one. Please refer to extref:{problem-reports}[Writing FreeBSD Problem Reports] for information on how to write a really good PR. + [NOTE] ====== Please do not submit a man:shar[1] archive of the entire port; instead, use man:git-format-patch[1] or man:diff[1] `-ruN`. In this way, committers can much more easily see exactly what changes are being made. The Porter's Handbook section on extref:{porters-handbook}[Upgrading, port-upgrading] has more information. ====== . Wait + At some stage a committer will deal with your PR. It may take minutes, or it may take one or two weeks - so please be patient. If it takes any longer, please seek for help on mailing lists ({freebsd-ports}), IRC: #bsdports on EFNet or #freebsd-ports on Libera for example. . Give feedback + If a committer finds a problem with your changes, they will most likely refer it back to you. A prompt response will help get your PR committed faster, and is better for maintaining a thread of conversation when trying to resolve any problems. . And Finally + Your changes will be committed and your port will have been updated. The PR will then be closed by the committer. That's it! ==== ===== Ensure your ports continue to build correctly This section is about discovering and fixing problems that stop your ports from building correctly. FreeBSD only guarantees that the Ports Collection works on the `-STABLE` branches. In theory, you should be able to get by with running the latest release of each stable branch (since the ABIs are not supposed to change) but if you can run the branch, that is even better. Since the majority of FreeBSD installations run on PC-compatible machines (what is termed the `i386` architecture), we expect you to keep the port working on that architecture. We prefer that ports also work on the `amd64` architecture running native. It is completely fair to ask for help if you do not have one of these machines. [NOTE] ==== The usual failure modes for non-`x86` machines are that the original programmers assumed that, for instance, pointers are `int`-s, or that a relatively lax older gcc compiler was being used. More and more, application authors are reworking their code to remove these assumptions - but if the author is not actively maintaining their code, you may need to do this yourself. ==== These are the tasks you need to perform to ensure your port is able to be built: [.procedure] ==== . Watch for build failures + Check your mail for mail from `pkg-fallout@FreeBSD.org` and the http://portscout.FreeBSD.org[distfiles scanner] to see if any of the port which are failing to build are out of date. . Collect information + Once you are aware of a problem, collect information to help you fix it. Build errors reported by `pkg-fallout` are accompanied by logs which will show you where the build failed. If the failure was reported to you by a user, ask them to send you information which may help in diagnosing the problem, such as: ** Build logs ** The commands and options used to build the port (including options set in [.filename]#/etc/make.conf#) ** A list of packages installed on their system as shown by man:pkg-info[8] ** The version of FreeBSD they are running as shown by man:uname[1] `-a` ** When their ports collection was last updated ** When their ports tree and [.filename]#INDEX# was last updated . Investigate and find a solution + Unfortunately there is no straightforward process to follow to do this. Remember, though: if you are stuck, ask for help! The {freebsd-ports} is a good place to start, and the upstream developers are often very helpful. . Submit changes + Just as with updating a port, you should now incorporate changes, review and test, submit your changes in a PR, and provide feedback if required. . Send patches to upstream authors + In some cases, you will have to make patches to the port to make it run on FreeBSD. Some (but not all) upstream authors will accept such patches back into their code for the next release. If so, this may even help their users on other BSD-based systems as well and perhaps save duplicated effort. Please consider sending any applicable patches to the authors as a courtesy. ==== ===== Investigate bug reports and PRs related to your port This section is about discovering and fixing bugs. FreeBSD-specific bugs are generally caused by assumptions about the build and runtime environments that do not apply to FreeBSD. You are less likely to encounter a problem of this type, but it can be more subtle and difficult to diagnose. These are the tasks you need to perform to ensure your port continues to work as intended: [.procedure] ==== . Respond to bug reports + Bugs may be reported to you through email via the https://bugs.FreeBSD.org/search/[Problem Report database]. Bugs may also be reported directly to you by users. + You should respond to PRs and other reports within 14 days, but please try not to take that long. Try to respond as soon as possible, even if it is just to say you need some more time before you can work on the PR. + If you have not responded after 14 days, any committer may commit from a PR that you have not responded to via a `maintainer-timeout`. . Collect information + If the person reporting the bug has not also provided a fix, you need to collect the information that will allow you to generate one. + If the bug is reproducible, you can collect most of the required information yourself. If not, ask the person who reported the bug to collect the information for you, such as: ** A detailed description of their actions, expected program behavior and actual behavior ** Copies of input data used to trigger the bug ** Information about their build and execution environment - for example, a list of installed packages and the output of man:env[1] ** Core dumps ** Stack traces . Eliminate incorrect reports + Some bug reports may be incorrect. For example, the user may have simply misused the program; or their installed packages may be out of date and require updating. Sometimes a reported bug is not specific to FreeBSD. In this case report the bug to the upstream developers. If the bug is within your capabilities to fix, you can also patch the port so that the fix is applied before the next upstream release. . Find a solution + As with build errors, you will need to sort out a fix to the problem. Again, remember to ask if you are stuck! . Submit or approve changes + Just as with updating a port, you should now incorporate changes, review and test, and submit your changes in a PR (or send a follow-up if a PR already exists for the problem). If another user has submitted changes in the PR, you can also send a follow-up saying whether or not you approve the changes. ==== ===== Providing support Part of being a maintainer is providing support - not for the software in general - but for the port and any FreeBSD-specific quirks and problems. Users may contact you with questions, suggestions, problems and patches. Most of the time their correspondence will be specific to FreeBSD. Occasionally you may have to invoke your skills in diplomacy, and kindly point users seeking general support to the appropriate resources. Less frequently you will encounter a person asking why the `RPMS` are not up to date or how can they get the software to run under Foo Linux. Take the opportunity to tell them that your port is up to date (if it is, of course!), and suggest that they try FreeBSD. Sometimes users and developers will decide that you are a busy person whose time is valuable and do some of the work for you. For example, they might: * submit a PR or send you patches to update your port, * investigate and perhaps provide a fix to a PR, or * otherwise submit changes to your port. In these cases your main obligation is to respond in a timely manner. Again, the timeout for non-responsive maintainers is 14 days. After this period changes may be committed unapproved. They have taken the trouble to do this for you; so please try to at least respond promptly. Then review, approve, modify or discuss their changes with them as soon as possible. If you can make them feel that their contribution is appreciated (and it should be) you will have a better chance persuading them to do more things for you in the future :-). [[fix-broken]] === Finding and fixing a broken port There are some really good places to find a port that needs some attention. You can use the https://bugs.freebsd.org/search[web interface] to the Problem Report database to search through and view unresolved PRs. The majority of ports PRs are updates, but with a little searching and skimming over synopses you should be able to find something interesting to work on (the `sw-bug` class is a good place to start). -The other place is the http://portsmon.FreeBSD.org/[FreeBSD Ports Monitoring System]. -In particular look for unmaintained ports with build errors and ports that are marked `BROKEN`. - https://portsfallout.com/[PortsFallout] shows port issues gathered from the FreeBSD package building. It is OK to send changes for a maintained port as well, but remember to ask the maintainer in case they are already working on the problem. Once you have found a bug or problem, collect information, investigate and fix! If there is an existing PR, follow up to that. Otherwise create a new PR. Your changes will be reviewed and, if everything checks out, committed. -[NOTE] -====== -The FreeBSD Ports Monitoring System (portsmon) is currently not working due to latest Python updates. -====== - [[mortal-coil]] === When to call it quits As your interests and commitments change, you may find that you no longer have time to continue some (or all) of your ports contributions. That is fine! Please let us know if you are no longer using a port or have otherwise lost time or interest in being a maintainer. In this way we can go ahead and allow other people to try to work on existing problems with the port without waiting for your response. Remember, FreeBSD is a volunteer project, so if maintaining a port is no fun any more, it is probably time to let someone else do it! In any case, the Ports Management Team (`portmgr`) reserves the right to reset your maintainership if you have not actively maintained your port in some time. (Currently, this is set to 3 months.) By this, we mean that there are unresolved problems or pending updates that have not been worked on during that time. [[resources]] === Resources for ports maintainers and contributors The extref:{porters-handbook}[Porter's Handbook] is your hitchhiker's guide to the ports system. Keep it handy! extref:{problem-reports}[Writing FreeBSD Problem Reports] describes how to best formulate and submit a PR. In 2005 more than eleven thousand ports PRs were submitted! Following this article will greatly assist us in reducing the time needed to handle your PRs. The https://bugs.freebsd.org/bugzilla/query.cgi[Problem Report database]. -The http://portsmon.FreeBSD.org/[FreeBSD Ports Monitoring System (portsmon)] can show you cross-referenced information about ports such as build errors and problem reports. -If you are a maintainer you can use it to check on the build status of your ports. -As a contributor you can use it to find broken and unmaintained ports that need to be fixed. - The http://portscout.FreeBSD.org[FreeBSD Ports distfile scanner (portscout)] can show you ports for which the distfiles are not fetchable. You can check on your own ports or use it to find ports that need their `MASTER_SITES` updated. package:ports-mgmt/poudriere[] is the most thorough way to test a port through the entire cycle of installation, packaging, and deinstallation. Documentation is located at the https://github.com/freebsd/poudriere[poudriere github repository] man:portlint[1] is an application which can be used to verify that your port conforms to many important stylistic and functional guidelines. portlint is a simple heuristic application, so you should use it __only as a guide__. If portlint suggests changes which seem unreasonable, consult the extref:{porters-handbook}[Porter's Handbook] or ask for advice. The {freebsd-ports} is for general ports-related discussion. It is a good place to ask for help. You can link:https://lists.freebsd.org/[subscribe, or read and search the list archives]. Reading the archives of the {freebsd-ports-bugs} and the {svn-ports-head} may also be of interest. https://portsfallout.com/[PortsFallout] is a place to help in searching for the https://lists.freebsd.org/archives/freebsd-pkg-fallout/[FreeBSD package-fallout archive]. [[ideas-contributing]] == Getting Started in Other Areas Looking for something interesting to get started that is not mentioned elsewhere in this article? The FreeBSD Project has several Wiki pages containing areas within which new contributors can get ideas on how to get started. The https://wiki.freebsd.org/JuniorJobs[Junior Jobs] page has a list of projects that might be of interest to people just getting started in FreeBSD, and want to work on interesting things to get their feet wet. The https://wiki.freebsd.org/IdeasPage[Ideas Page] contains various "nice to have" or "interesting" things to work on in the Project. diff --git a/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc b/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc index 2a8cf3e639..9061a38d2b 100644 --- a/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc +++ b/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc @@ -1,132 +1,112 @@ --- title: Chapter 16. Keeping Up prev: books/porters-handbook/order next: books/porters-handbook/uses description: How to keep up the FreeBSD Ports Collection tags: ["keeping up", "ports", "updating", "FreshPorts"] showBookMenu: true weight: 16 path: "/books/porters-handbook/" --- [[keeping-up]] = Keeping Up :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 16 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] The FreeBSD Ports Collection is constantly changing. Here is some information on how to keep up. [[freshports]] == FreshPorts One of the easiest ways to learn about updates that have already been committed is by subscribing to http://www.FreshPorts.org/[FreshPorts]. Multiple ports can be monitored. Maintainers are strongly encouraged to subscribe, because they will receive notification of not only their own changes, but also any changes that any other FreeBSD committer has made. (These are often necessary to keep up with changes in the underlying ports framework-although it would be most polite to receive an advance heads-up from those committing such changes, sometimes this is overlooked or impractical. Also, in some cases, the changes are very minor in nature. We expect everyone to use their best judgement in these cases.) To use FreshPorts, an account is required. Those with registered email addresses at `@FreeBSD.org` will see the opt-in link on the right-hand side of the web pages. Those who already have a FreshPorts account but are not using a `@FreeBSD.org` email address can change the email to `@FreeBSD.org`, subscribe, then change it back again. FreshPorts also has a sanity test feature which automatically tests each commit to the FreeBSD ports tree. If subscribed to this service, a committer will receive notifications of any errors which FreshPorts detects during sanity testing of their commits. [[cgit]] == The Web Interface to the Source Repository It is possible to browse the files in the source repository by using a web interface. Changes that affect the entire port system are now documented in the https://cgit.freebsd.org/ports/tree/CHANGES[CHANGES] file. Changes that affect individual ports are now documented in the https://cgit.FreeBSD.org/ports/tree/UPDATING[UPDATING] file. However, the definitive answer to any question is undoubtedly to read the source code of https://cgit.FreeBSD.org/ports/tree/Mk/bsd.port.mk[bsd.port.mk], and associated files. [[ports-mailing-list]] == The FreeBSD Ports Mailing List As a ports maintainer, consider subscribing to {freebsd-ports}. Important changes to the way ports work will be announced there, and then committed to [.filename]#CHANGES#. If the volume of messages on this mailing list is too high, consider following {freebsd-ports-announce} which contains only announcements. [[build-cluster]] == The FreeBSD Port Building Cluster One of the least-publicized strengths of FreeBSD is that an entire cluster of machines is dedicated to continually building the Ports Collection, for each of the major OS releases and for each Tier-1 architecture. Individual ports are built unless they are specifically marked with `IGNORE`. Ports that are marked with `BROKEN` will still be attempted, to see if the underlying problem has been resolved. (This is done by passing `TRYBROKEN` to the port's [.filename]#Makefile#.) [[distfile-survey]] == Portscout: the FreeBSD Ports Distfile Scanner The build cluster is dedicated to building the latest release of each port with distfiles that have already been fetched. However, as the Internet continually changes, distfiles can quickly go missing. http://portscout.FreeBSD.org[Portscout], the FreeBSD Ports distfile scanner, attempts to query every download site for every port to find out if each distfile is still available. Portscout can generate HTML reports and send emails about newly available ports to those who request them. Unless not otherwise subscribed, maintainers are asked to check periodically for changes, either by hand or using the RSS feed. Portscout's first page gives the email address of the port maintainer, the number of ports the maintainer is responsible for, the number of those ports with new distfiles, and the percentage of those ports that are out-of-date. The search function allows for searching by email address for a specific maintainer, and for selecting whether only out-of-date ports are shown. Upon clicking on a maintainer's email address, a list of all of their ports is displayed, along with port category, current version number, whether or not there is a new version, when the port was last updated, and finally when it was last checked. A search function on this page allows the user to search for a specific port. Clicking on a port name in the list displays the http://freshports.org[FreshPorts] port information. Additional documentation is available in the https://github.com/freebsd/portscout[Portscout repository]. - -[[portsmon]] -== The FreeBSD Ports Monitoring System - -Another handy resource is the http://portsmon.FreeBSD.org[FreeBSD Ports Monitoring System] (also known as `portsmon`). -This system comprises a database that processes information from several sources and allows it to be browsed via a web interface. -Currently, the ports Problem Reports (PRs), the error logs from the build cluster, and individual files from the ports collection are used. -In the future, this will be expanded to include the distfile survey, as well as other sources. - -To get started, use the http://portsmon.FreeBSD.org/portoverview.py[Overview of One Port] search page to find all the information about a port. - -This is the only resource available that maps PR entries to portnames. -PR submitters do not always include the portname in their Synopsis, although we would prefer that they did. -So, `portsmon` is a good place to find out whether an existing port has any PRs filed against it, any build errors, -or if a new port the porter is considering creating has already been submitted. - -[NOTE] -====== -The FreeBSD Ports Monitoring System (portsmon) is currently not working due to latest Python updates. -====== diff --git a/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc b/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc index 9693c0ca93..f04dfbe22f 100644 --- a/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc +++ b/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc @@ -1,552 +1,552 @@ --- title: Chapter 13. Dos and Don'ts prev: books/porters-handbook/security next: books/porters-handbook/porting-samplem description: A list of common dos and don'ts that are encountered during the FreeBSD porting process tags: ["dos", "don'ts", "porting", "ports", "guide"] showBookMenu: true weight: 13 path: "/books/porters-handbook/" --- [[porting-dads]] = Dos and Don'ts :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 13 :partnums: :source-highlighter: rouge :experimental: :freebsd-version: __FreeBSD_version :freebsd: __FreeBSD__ :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[dads-intro]] == Introduction Here is a list of common dos and don'ts that are encountered during the porting process. Check the port against this list, but also check ports in the https://bugs.FreeBSD.org/search/[PR database] that others have submitted. Submit any comments on ports as described in extref:{contributing}[Bug Reports and General Commentary, CONTRIB-GENERAL]. Checking ports in the PR database will both make it faster for us to commit them, and prove that you know what you are doing. [[porting-wrkdir]] == `WRKDIR` Do not write anything to files outside `WRKDIR`. `WRKDIR` is the only place that is guaranteed to be writable during the port build (see extref:{handbook}[ installing ports from a CDROM, PORTS-CD] for an example of building ports from a read-only tree). The [.filename]##pkg-*## files can be modified by crossref:pkg-files[pkg-names,redefining a variable] rather than overwriting the file. [[porting-wrkdirprefix]] == `WRKDIRPREFIX` Make sure the port honors `WRKDIRPREFIX`. Most ports do not have to worry about this. In particular, when referring to a `WRKDIR` of another port, note that the correct location is [.filename]#${WRKDIRPREFIX}${PORTSDIR}/subdir/name/work# not [.filename]#${PORTSDIR}/subdir/name/work# or [.filename]#${.CURDIR}/../../subdir/name/work# or some such. [[porting-versions]] == Differentiating Operating Systems and OS Versions Some code needs modifications or conditional compilation based upon what version of FreeBSD Unix it is running under. The preferred way to tell FreeBSD versions apart are the `{freebsd-version}` and `{freebsd}` macros defined in https://cgit.freebsd.org/src/tree/sys/sys/param.h[sys/param.h]. If this file is not included add the code, [.programlisting] .... #include .... to the proper place in the [.filename]#.c# file. `{freebsd}` is defined in all versions of FreeBSD as their major version number. For example, in FreeBSD 9.x, `{freebsd}` is defined to be `9`. [.programlisting] .... #if __FreeBSD__ >= 9 # if __FreeBSD_version >= 901000 /* 9.1+ release specific code here */ # endif #endif .... A complete list of `{freebsd-version}` values is available in crossref:versions[versions,__FreeBSD_version Values]. [[dads-after-port-mk]] == Writing Something After bsd.port.mk Do not write anything after the `.include ` line. It usually can be avoided by including [.filename]#bsd.port.pre.mk# somewhere in the middle of the [.filename]#Makefile# and [.filename]#bsd.port.post.mk# at the end. [IMPORTANT] ==== Include either the [.filename]#bsd.port.pre.mk#/[.filename]#bsd.port.post.mk# pair or [.filename]#bsd.port.mk# only; do not mix these two usages. ==== [.filename]#bsd.port.pre.mk# only defines a few variables, which can be used in tests in the [.filename]#Makefile#, [.filename]#bsd.port.post.mk# defines the rest. Here are some important variables defined in [.filename]#bsd.port.pre.mk# (this is not the complete list, please read [.filename]#bsd.port.mk# for the complete list). [.informaltable] [cols="1,1", frame="none", options="header"] |=== | Variable | Description |`ARCH` |The architecture as returned by `uname -m` (for example, `i386`) |`OPSYS` |The operating system type, as returned by `uname -s` (for example, `FreeBSD`) |`OSREL` |The release version of the operating system (for example, `2.1.5` or `2.2.7`) |`OSVERSION` |The numeric version of the operating system; the same as crossref:versions[versions,`{freebsd-version}`]. |`LOCALBASE` |The base of the "local" tree (for example, `/usr/local`) |`PREFIX` |Where the port installs itself (see crossref:testing[porting-prefix,more on `PREFIX`]). |=== [NOTE] ==== When `MASTERDIR` is needed, always define it before including [.filename]#bsd.port.pre.mk#. ==== Here are some examples of things that can be added after [.filename]#bsd.port.pre.mk#: [.programlisting] .... # no need to compile lang/perl5 if perl5 is already in system .if ${OSVERSION} > 300003 BROKEN= perl is in system .endif .... Always use tab instead of spaces after `BROKEN=`. [[dads-sh-exec]] == Use the `exec` Statement in Wrapper Scripts If the port installs a shell script whose purpose is to launch another program, and if launching that program is the last action performed by the script, make sure to launch the program using the `exec` statement, for instance: [.programlisting] .... #!/bin/sh exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@" .... The `exec` statement replaces the shell process with the specified program. If `exec` is omitted, the shell process remains in memory while the program is executing, and needlessly consumes system resources. [[dads-rational]] == Do Things Rationally The [.filename]#Makefile# should do things in a simple and reasonable manner. Making it a couple of lines shorter or more readable is always better. Examples include using a make `.if` construct instead of a shell `if` construct, not redefining `do-extract` if redefining `EXTRACT*` is enough, and using `GNU_CONFIGURE` instead of `CONFIGURE_ARGS += --prefix=${PREFIX}`. If a lot of new code is needed to do something, there may already be an implementation of it in [.filename]#bsd.port.mk#. While hard to read, there are a great many seemingly-hard problems for which [.filename]#bsd.port.mk# already provides a shorthand solution. [[dads-cc]] == Respect Both `CC` and `CXX` The port must respect both `CC` and `CXX`. What we mean by this is that the port must not set the values of these variables absolutely, overriding existing values; instead, it may append whatever values it needs to the existing values. This is so that build options that affect all ports can be set globally. If the port does not respect these variables, please add `NO_PACKAGE=ignores either cc or cxx` to the [.filename]#Makefile#. Here is an example of a [.filename]#Makefile# respecting both `CC` and `CXX`. Note the `?=`: [.programlisting] .... CC?= gcc .... [.programlisting] .... CXX?= g++ .... Here is an example which respects neither `CC` nor `CXX`: [.programlisting] .... CC= gcc .... [.programlisting] .... CXX= g++ .... Both `CC` and `CXX` can be defined on FreeBSD systems in [.filename]#/etc/make.conf#. The first example defines a value if it was not previously set in [.filename]#/etc/make.conf#, preserving any system-wide definitions. The second example clobbers anything previously defined. [[dads-cflags]] == Respect `CFLAGS` The port must respect `CFLAGS`. What we mean by this is that the port must not set the value of this variable absolutely, overriding the existing value. Instead, it may append whatever values it needs to the existing value. This is so that build options that affect all ports can be set globally. If it does not, please add `NO_PACKAGE=ignores cflags` to the [.filename]#Makefile#. Here is an example of a [.filename]#Makefile# respecting `CFLAGS`. Note the `+=`: [.programlisting] .... CFLAGS+= -Wall -Werror .... Here is an example which does not respect `CFLAGS`: [.programlisting] .... CFLAGS= -Wall -Werror .... `CFLAGS` is defined on FreeBSD systems in [.filename]#/etc/make.conf#. The first example appends additional flags to `CFLAGS`, preserving any system-wide definitions. The second example clobbers anything previously defined. Remove optimization flags from the third party [.filename]##Makefile##s. The system `CFLAGS` contains system-wide optimization flags. An example from an unmodified [.filename]#Makefile#: [.programlisting] .... CFLAGS= -O3 -funroll-loops -DHAVE_SOUND .... Using system optimization flags, the [.filename]#Makefile# would look similar to this example: [.programlisting] .... CFLAGS+= -DHAVE_SOUND .... [[dads-verbose-logs]] == Verbose Build Logs Make the port build system display all commands executed during the build stage. Complete build logs are crucial to debugging port problems. Non-informative build log example (bad): [.programlisting] .... CC source1.o CC source2.o CCLD someprogram .... Verbose build log example (good): [.programlisting] .... cc -O2 -pipe -I/usr/local/include -c -o source1.o source1.c cc -O2 -pipe -I/usr/local/include -c -o source2.o source2.c cc -o someprogram source1.o source2.o -L/usr/local/lib -lsomelib .... Some build systems such as CMake, ninja, and GNU configure are set up for verbose logging by the ports framework. In other cases, ports might need individual tweaks. [[dads-feedback]] == Feedback Do send applicable changes and patches to the upstream maintainer for inclusion in the next release of the code. This makes updating to the next release that much easier. [[dads-readme]] == README.html [.filename]#README.html# is not part of the port, but generated by `make readme`. Do not include this file in patches or commits. [NOTE] ==== If `make readme` fails, make sure that the default value of `ECHO_MSG` has not been modified by the port. ==== [[dads-noinstall]] == Marking a Port Not Installable with `BROKEN`, `FORBIDDEN`, or `IGNORE` In certain cases, users must be prevented from installing a port. There are several variables that can be used in a port's [.filename]#Makefile# to tell the user that the port cannot be installed. The value of these make variables will be the reason that is shown to users for why the port refuses to install itself. Please use the correct make variable. -Each variable conveys radically different meanings, both to users and to automated systems that depend on [.filename]##Makefile##s, such as crossref:keeping-up[build-cluster,the ports build cluster], crossref:keeping-up[freshports,FreshPorts], and crossref:keeping-up[portsmon,portsmon]. +Each variable conveys radically different meanings, both to users and to automated systems that depend on [.filename]##Makefile##s, such as crossref:keeping-up[build-cluster,the ports build cluster], and crossref:keeping-up[freshports,FreshPorts]. [[dads-noinstall-variables]] === Variables * `BROKEN` is reserved for ports that currently do not compile, install, deinstall, or run correctly. Use it for ports where the problem is believed to be temporary. + If instructed, the build cluster will still attempt to try to build them to see if the underlying problem has been resolved. (However, in general, the cluster is run without this.) + For instance, use `BROKEN` when a port: ** does not compile ** fails its configuration or installation process ** installs files outside of [.filename]#${PREFIX}# ** does not remove all its files cleanly upon deinstall (however, it may be acceptable, and desirable, for the port to leave user-modified files behind) ** has runtime issues on systems where it is supposed to run fine. * `FORBIDDEN` is used for ports that contain a security vulnerability or induce grave concern regarding the security of a FreeBSD system with a given port installed (for example, a reputably insecure program or a program that provides easily exploitable services). Mark ports as `FORBIDDEN` as soon as a particular piece of software has a vulnerability and there is no released upgrade. Ideally upgrade ports as soon as possible when a security vulnerability is discovered so as to reduce the number of vulnerable FreeBSD hosts (we like being known for being secure), however sometimes there is a noticeable time gap between disclosure of a vulnerability and an updated release of the vulnerable software. Do not mark a port `FORBIDDEN` for any reason other than security. * `IGNORE` is reserved for ports that must not be built for some other reason. Use it for ports where the problem is believed to be structural. The build cluster will not, under any circumstances, build ports marked as `IGNORE`. For instance, use `IGNORE` when a port: ** does not work on the installed version of FreeBSD ** has a distfile which may not be automatically fetched due to licensing restrictions ** does not work with some other currently installed port (for instance, the port depends on package:www/apache20[] but package:www/apache22[] is installed) + [NOTE] ==== If a port would conflict with a currently installed port (for example, if they install a file in the same place that performs a different function), crossref:makefiles[conflicts,use `CONFLICTS` instead]. `CONFLICTS` will set `IGNORE` by itself. ==== [[dads-noinstall-notes]] === Implementation Notes Do not quote the values of `BROKEN`, `IGNORE`, and related variables. Due to the way the information is shown to the user, the wording of messages for each variable differ: [.programlisting] .... BROKEN= fails to link with base -lcrypto .... [.programlisting] .... IGNORE= unsupported on recent versions .... resulting in this output from `make describe`: [.programlisting] .... ===> foobar-0.1 is marked as broken: fails to link with base -lcrypto. .... [.programlisting] .... ===> foobar-0.1 is unsupported on recent versions. .... [[dads-arch]] == Architectural Considerations [[dads-arch-general]] === General Notes on Architectures FreeBSD runs on many more processor architectures than just the well-known x86-based ones. Some ports have constraints which are particular to one or more of these architectures. For the list of supported architectures, run: [.programlisting] .... cd ${SRCDIR}; make targets .... The values are shown in the form `TARGET`/`TARGET_ARCH`. The ports read-only makevar `ARCH` is set based on the value of `TARGET_ARCH`. Port [.filename]##Makefile##s should test the value of this Makevar. [[dads-arch-neutral]] === Marking a Port as Architecture Neutral Ports that do not have any architecture-dependent files or requirements are identified by setting `NO_ARCH=yes`. [NOTE] ==== `NO_ARCH` is meant to indicate that there is no need to build a package for each of the supported architectures. The goal is to reduce the amount of resources spent on building and distributing the packages such as network bandwidth and disk space on mirrors and on distribution media. Currently, however, our package infrastructure (e.g., package managers, mirrors, and package builders) is not set up to fully benefit from `NO_ARCH`. ==== [[dads-arch-ignore]] === Marking a Port as Ignored Only On Certain Architectures * To mark a port as ``IGNORE``d only on certain architectures, there are two other convenience variables that will automatically set `IGNORE`: `ONLY_FOR_ARCHS` and `NOT_FOR_ARCHS`. Examples: + [.programlisting] .... ONLY_FOR_ARCHS= i386 amd64 .... + [.programlisting] .... NOT_FOR_ARCHS= ia64 sparc64 .... + A custom `IGNORE` message can be set using `ONLY_FOR_ARCHS_REASON` and `NOT_FOR_ARCHS_REASON`. Per architecture entries are possible with `ONLY_FOR_ARCHS_REASON_ARCH` and `NOT_FOR_ARCHS_REASON_ARCH`. [[dads-arch-i386]] * If a port fetches i386 binaries and installs them, set `IA32_BINARY_PORT`. If this variable is set, [.filename]#/usr/lib32# must be present for IA32 versions of libraries and the kernel must support IA32 compatibility. If one of these two dependencies is not satisfied, `IGNORE` will be set automatically. [[dads-arch-cluster]] === Cluster-Specific Considerations * Some ports attempt to tune themselves to the exact machine they are being built on by specifying `-march=native` to the compiler. This should be avoided: either list it under an off-by-default option, or delete it entirely. + Otherwise, the default package produced by the build cluster might not run on every single machine of that `ARCH`. [[dads-deprecated]] == Marking a Port for Removal with `DEPRECATED` or `EXPIRATION_DATE` Do remember that `BROKEN` and `FORBIDDEN` are to be used as a temporary resort if a port is not working. Permanently broken ports will be removed from the tree entirely. When it makes sense to do so, users can be warned about a pending port removal with `DEPRECATED` and `EXPIRATION_DATE`. The former is a string stating why the port is scheduled for removal; the latter is a string in ISO 8601 format (YYYY-MM-DD). Both will be shown to the user. It is possible to set `DEPRECATED` without an `EXPIRATION_DATE` (for instance, recommending a newer version of the port), but the converse does not make any sense. There is no set policy on how much notice to give. Current practice seems to be one month for security-related issues and two months for build issues. This also gives any interested committers a little time to fix the problems. [[dads-dot-error]] == Avoid Use of the `.error` Construct The correct way for a [.filename]#Makefile# to signal that the port cannot be installed due to some external factor (for instance, the user has specified an illegal combination of build options) is to set a non-blank value to `IGNORE`. This value will be formatted and shown to the user by `make install`. It is a common mistake to use `.error` for this purpose. The problem with this is that many automated tools that work with the ports tree will fail in this situation. The most common occurrence of this is seen when trying to build [.filename]#/usr/ports/INDEX# (see crossref:testing[make-describe,Running `make describe`]). However, even more trivial commands such as `make maintainer` also fail in this scenario. This is not acceptable. [[dot-error-breaks-index]] .How to Avoid Using `.error` [example] ==== The first of the next two [.filename]#Makefile# snippets will cause `make index` to fail, while the second one will not: [.programlisting] .... .error "option is not supported" .... [.programlisting] .... IGNORE=option is not supported .... ==== [[dads-sysctl]] == Usage of sysctl The usage of [.filename]#sysctl# is discouraged except in targets. This is because the evaluation of any ``makevar``s, such as used during `make index`, then has to run the command, further slowing down that process. Only use man:sysctl[8] through `SYSCTL`, as it contains the fully qualified path and can be overridden, if one has such a special need. [[dads-rerolling-distfiles]] == Rerolling Distfiles Sometimes the authors of software change the content of released distfiles without changing the file's name. Verify that the changes are official and have been performed by the author. It has happened in the past that the distfile was silently altered on the download servers with the intent to cause harm or compromise end user security. Put the old distfile aside, download the new one, unpack them and compare the content with man:diff[1]. If there is nothing suspicious, update [.filename]#distinfo#. [IMPORTANT] ==== Be sure to summarize the differences in the PR and commit log, so that other people know that nothing bad has happened. ==== Contact the authors of the software and confirm the changes with them. [[dads-use-posix-standards]] == Use POSIX Standards FreeBSD ports generally expect POSIX compliance. Some software and build systems make assumptions based on a particular operating system or environment that can cause problems when used in a port. Do not use [.filename]#/proc# if there are any other ways of getting the information. For example, `setprogname(argv[0])` in `main()` and then man:getprogname[3] to know the executable name. Do not rely on behavior that is undocumented by POSIX. Do not record timestamps in the critical path of the application if it also works without. Getting timestamps may be slow, depending on the accuracy of timestamps in the OS. If timestamps are really needed, determine how precise they have to be and use an API which is documented to just deliver the needed precision. A number of simple syscalls (for example man:gettimeofday[2], man:getpid[2]) are much faster on Linux(R) than on any other operating system due to caching and the vsyscall performance optimizations. Do not rely on them being cheap in performance-critical applications. In general, try hard to avoid syscalls if possible. Do not rely on Linux(R)-specific socket behavior. In particular, default socket buffer sizes are different (call man:setsockopt[2] with `SO_SNDBUF` and `SO_RCVBUF`, and while Linux(R)'s man:send[2] blocks when the socket buffer is full, FreeBSD's will fail and set `ENOBUFS` in errno. If relying on non-standard behavior is required, encapsulate it properly into a generic API, do a check for the behavior in the configure stage, and stop if it is missing. Check the https://www.freebsd.org/cgi/man.cgi[man pages] to see if the function used is a POSIX interface (in the "STANDARDS" section of the man page). Do not assume that [.filename]#/bin/sh# is bash. Ensure that a command line passed to man:system[3] will work with a POSIX compliant shell. A list of common bashisms is available https://wiki.ubuntu.com/DashAsBinSh[here]. Check that headers are included in the POSIX or man page recommended way. For example, [.filename]#sys/types.h# is often forgotten, which is not as much of a problem for Linux(R) as it is for FreeBSD. [[dads-misc]] == Miscellanea Always double-check [.filename]#pkg-descr# and [.filename]#pkg-plist#. If reviewing a port and a better wording can be achieved, do so. Do not copy more copies of the GNU General Public License into our system, please. Please be careful to note any legal issues! Do not let us illegally distribute software! diff --git a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc index 3cd5e01f68..14ddf24af6 100644 --- a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc +++ b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc @@ -1,300 +1,290 @@ --- title: Chapter 11. Upgrading a Port prev: books/porters-handbook/testing next: books/porters-handbook/security description: Upgrading a FreeBSD Port tags: ["upgrading", "port", "git"] showBookMenu: true weight: 11 path: "/books/porters-handbook/" --- [[port-upgrading]] = Upgrading a Port :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 11 :partnums: :source-highlighter: rouge :experimental: :images-path: books/porters-handbook/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] When a port is not the most recent version available from the authors, update the local working copy of [.filename]#/usr/ports#. The port might have already been updated to the new version. When working with more than a few ports, it will probably be easier to use Git to keep the whole ports collection up-to-date, as described in the extref:{handbook}[Handbook, ports-using]. This will have the added benefit of tracking all the port's dependencies. The next step is to see if there is an update already pending. To do this, there are two options. There is a searchable interface to the https://bugs.freebsd.org/search/[FreeBSD Problem Report (PR) or bug database]. Select `Ports & Packages` in the `Product` multiple select menu, and enter the name of the port in the `Summary` field. -However, sometimes people forget to put the name of the port into the Summary field in an unambiguous fashion. -In that case, try searching in the `Comment` field in the `Detailled Bug Information` section, or try the crossref:keeping-up[portsmon,FreeBSD Ports Monitoring System] (also known as `portsmon`). -This system attempts to classify port PRs by portname. -To search for PRs about a particular port, use the http://portsmon.FreeBSD.org/portoverview.py[Overview of One Port]. - -[NOTE] -====== -The FreeBSD Ports Monitoring System (portsmon) is currently not working due to latest Python updates. -====== - If there is no pending PR, the next step is to send an email to the port's maintainer, as shown by `make maintainer`. That person may already be working on an upgrade, or have a reason to not upgrade the port right now (because of, for example, stability problems of the new version), and there is no need to duplicate their work. Note that unmaintained ports are listed with a maintainer of `ports@FreeBSD.org`, which is just the general ports mailing list, so sending mail there probably will not help in this case. If the maintainer asks you to do the upgrade or there is no maintainer, then help out FreeBSD by preparing the update! Please do this by using the man:diff[1] command in the base system. To create a suitable `diff` for a single patch, copy the file that needs patching to [.filename]#something.orig#, save the changes to [.filename]#something# and then create the patch: [source,shell] .... % diff -u something.orig something > something.diff .... Otherwise, either use the `git diff` method (<>) or copy the contents of the port to an entire different directory and use the result of the recursive man:diff[1] output of the new and old ports directories (for example, if the modified port directory is called [.filename]#superedit# and the original is in our tree as [.filename]#superedit.bak#, then save the result of `diff -ruN superedit.bak superedit`). Either unified or context diff is fine, but port committers generally prefer unified diffs. Note the use of the `-N` option-this is the accepted way to force diff to properly deal with the case of new files being added or old files being deleted. Before sending us the diff, please examine the output to make sure all the changes make sense. (In particular, make sure to first clean out the work directories with `make clean`). [NOTE] ==== If some files have been added, copied, moved, or removed, add this information to the problem report so that the committer picking up the patch will know what man:git[1] commands to run. ==== To simplify common operations with patch files, use `make makepatch` as described in crossref:slow-porting[slow-patch,Patching]. Other tools exists, like [.filename]#/usr/ports/Tools/scripts/patchtool.py#. Before using it, please read [.filename]#/usr/ports/Tools/scripts/README.patchtool#. If the port is unmaintained, and you are actively using it, please consider volunteering to become its maintainer. FreeBSD has over 4000 ports without maintainers, and this is an area where more volunteers are always needed. (For a detailed description of the responsibilities of maintainers, refer to the section in the extref:{developers-handbook}[Developer's Handbook, POLICIES-MAINTAINER].) To submit the diff, use the https://bugs.freebsd.org/submit/[bug submit form] (product `Ports & Packages`, component `Individual Port(s)`). Always include the category with the port name, followed by colon, and brief descripton of the issue. Examples: `_category/portname_: _add FOO option_`; `_category/portname_: _Update to X.Y_`. Please mention any added or deleted files in the message, as they have to be explicitly specified to man:git[1] when doing a commit. Do not compress or encode the diff. Before submitting the bug, review the extref:{problem-reports}[Writing the problem report, pr-writing] section in the Problem Reports article. It contains far more information about how to write useful problem reports. [IMPORTANT] ==== If the upgrade is motivated by security concerns or a serious fault in the currently committed port, please notify the {portmgr} to request immediate rebuilding and redistribution of the port's package. Unsuspecting users of `pkg` will otherwise continue to install the old version via `pkg install` for several weeks. ==== [NOTE] ==== Please use man:diff[1] or `git diff` to create updates to existing ports. Other formats include the whole file and make it impossible to see just what has changed. When diffs are not included, the entire update might be ignored. ==== Now that all of that is done, read about how to keep up-to-date in crossref:keeping-up[keeping-up,Keeping Up]. [[git-diff]] == Using Git to Make Patches When possible, please submit a man:git[1] patch or diff. They are easier to handle than diffs between "new and old" directories. It is easier to see what has changed, and to update the diff if something was modified in the Ports Collection since the work on it began, or if the committer asks for something to be fixed. Also, a patch generated with man:git-format-patch[1] or man:git-diff[1] can be easily applied with man:git-am[1] or man:git-apply[1] and will save some time for the committer. Finally, the git patch generated by man:git-format-patch[1] includes your author information and commit messages. These will be recorded in the log of the repository and this is the recommended way to submit your changes. [source,shell] .... % git clone https://git.FreeBSD.org/ports.git ~/my_wrkdir <.> <.> % cd ~/my_wrkdir .... <.> This can be anywhere, of course. Building ports is not limited to within [.filename]#/usr/ports/#. <.> https://git.FreeBSD.org/[git.FreeBSD.org] is the FreeBSD public Git server. See extref:{handbook}mirrors[FreeBSD Git Repository URL Table, git-url-table] for more information. While in the port directory, make any changes that are needed. If adding, moving, or removing a file, use `git` to track these changes: [source,shell] .... % git add new_file % git mv old_name new_name % git rm deleted_file .... Make sure to check the port using the checklist in crossref:quick-porting[porting-testing,Testing the Port] and crossref:quick-porting[porting-portlint,Checking the Port with `portlint`]. Before making the patch, fetch the latest repository and rebase the changes on top of it. Watch and follow the output carefully. If any of the files failed to rebase, it means that the upstream files changed while you were editing the same file, and the conflicts need to be resolved manually. [source,shell] .... % git fetch origin main % git rebase origin/main .... Check the changes staged for the patch: [source,shell] .... % git status % git diff --staged .... The last step is to make an unified diff or patch of the changes: To generate a patch with man:git-format-patch[1]: [source,shell] .... % git checkout -b my_branch % git commit % git format-patch main .... This will generate a patch named like `0001-foo.patch`. This is the preferred way as it would include author identity, and it is also easier when you are making a series of changes that are not meant to be squashed together. Alternatively, to generate an unified diff with man:git-diff[1]: [source,shell] .... % git diff --staged > ../`make -VPKGNAME`.diff .... This will generate a diff named like `foo-1.2.3.diff`. Where `foo` is replaced with the first line of the commit message, i.e., the subject of the commit message. After patch has been created, you can switch to the main branch for starting other developments. [source,shell] .... % git checkout main .... Once the patch is accepted and merged, you can delete the local development branch if you want: [source,shell] .... % git branch -D my_branch .... [NOTE] ==== If files have been added, moved, or removed, include the man:git[1] `add`, `mv`, and `rm` commands that were used. `git mv` must be run before the patch can be applied. `git add` or `git rm` must be run after the patch is applied. ==== Send the patch following the extref:{problem-reports}[problem report submission guidelines, pr-writing]. [[moved-and-updating-files]] == UPDATING and MOVED [[moved-and-updating-updating]] === /usr/ports/UPDATING If upgrading the port requires special steps like changing configuration files or running a specific program, it must be documented in this file. The format of an entry in this file is: [.programlisting] .... YYYYMMDD: AFFECTS: users of portcategory/portname AUTHOR: Your name Special instructions .... [TIP] ==== When including exact portmaster, portupgrade, and/or pkg instructions, please make sure to get the shell escaping right. For example, do _not_ use: [source,shell] .... # pkg delete -g -f docbook-xml* docbook-sk* docbook[2345]??-* docbook-4* .... As shown, the command will only work with bourne shells. Instead, use the form shown below, which will work with both bourne shell and c-shell: [source,shell] .... # pkg delete -g -f docbook-xml\* docbook-sk\* docbook\[2345\]\?\?-\* docbook-4\* .... ==== [NOTE] ==== It is recommended that the AFFECTS line contains a glob matching all the ports affected by the entry so that automated tools can parse it as easily as possible. If an update concerns all the existing BIND 9 versions the `AFFECTS` content must be `users of dns/bind9*`, it must _not_ be `users of BIND 9` ==== [[moved-and-updating-moved]] === /usr/ports/MOVED This file is used to list moved or removed ports. Each line in the file is made up of the name of the port, where the port was moved, when, and why. If the port was removed, the section detailing where it was moved can be left blank. Each section must be separated by the `|` (pipe) character, like so: [.programlisting] .... old name|new name (blank for deleted)|date of move|reason .... The date must be entered in the form `YYYY-MM-DD`. New entries are added to the end of the list to keep it in chronological order, with the oldest entry at the top of the list. If a port was removed but has since been restored, delete the line in this file that states that it was removed. If a port was renamed and then renamed back to its original name, add a new one with the intermediate name to the old name, and remove the old entry as to not create a loop. [NOTE] ==== Any changes must be validated with `Tools/scripts/MOVEDlint.awk`. If using a ports directory other than [.filename]#/usr/ports#, use: [source,shell] .... % cd /home/user/ports % env PORTSDIR=$PWD Tools/scripts/MOVEDlint.awk .... ==== diff --git a/website/content/en/projects/_index.adoc b/website/content/en/projects/_index.adoc index b5fe5bec93..95a59e3b41 100644 --- a/website/content/en/projects/_index.adoc +++ b/website/content/en/projects/_index.adoc @@ -1,77 +1,76 @@ --- title: "FreeBSD Development Projects" sidenav: developers --- include::shared/en/urls.adoc[] = FreeBSD Development Projects In addition to the mainstream development path of FreeBSD, a number of developer groups are working on the cutting edge to expand FreeBSD's range of applications in new directions. Follow the links below to learn more about these exciting projects. If you feel that a project is missing, please send the URL and a short description (3-10 lines) to link:../mailto/[www@FreeBSD.org]. In addition, some of these projects regularly submit status reports, which can be viewed on the link:../status/[status reports page]. * <> * link:../advocacy/[Advocacy] * <> * <> * <> * <> * <> * <> * link:summerofcode[Google Summer of Code] [[documentation]] == Documentation * link:../docproj/[FreeBSD Documentation Project]: The FreeBSD Documentation Project is a group of people who maintain and write the documentation (such as the Handbook and FAQ) for the FreeBSD project. If you want to help with the documentation project, subscribe to the freebsd-doc@FreeBSD.org mailing list and participate. * link:newbies[FreeBSD Resources for Newbies]: A list of resources to help those new to FreeBSD and UNIX(R) in general. * http://www.freebsddiary.org/[The FreeBSD Diary]: A collection of how-to entries aimed at UNIX novices. The aim is to provide a set of step-by-step guides to installing and configuring various ports. * link:{developers-handbook}[The FreeBSD Developers' Handbook] * link:{contributing}[Contributing to FreeBSD] [[applications]] == Applications * link:../java/[Java(R) on FreeBSD]: This contains information on where to obtain the latest JDK(R) for FreeBSD, how to install and run it, and a list of Java(R) software that you may find interesting. * link:../gnome/[GNOME on FreeBSD]: This contains information on where to obtain the latest GNOME for FreeBSD, how to install and run it, latest project news and updates, FAQ covering FreeBSD-specific GNOME issues, application porting guidelines and much more. * https://freebsd.kde.org[KDE on FreeBSD]: This contains links to the latest KDE releases for FreeBSD, as well as documentation and tutorials about how to install and run KDE on FreeBSD. Project news and a FreeBSD-specific FAQ are also available. * http://www.mono-project.com/docs/about-mono/supported-platforms/bsd/[Mono on FreeBSD]: Here you can find information about the state of Mono and C# for FreeBSD. * https://porting.openoffice.org/freebsd/[OpenOffice.org on FreeBSD]: Information about the various OpenOffice.org ports. * link:../ports/[FreeBSD Ports Collection]: The FreeBSD Ports Collection provides an easy way to compile and install a wide range of applications with a minimum amount of effort. A list of current ports is available along with a search mechanism to see if a specific application exists in the Ports Collection. * https://portscout.FreeBSD.org/[FreeBSD Ports distfiles scanner]: A list which checks the Ports Collection for unfetchable distfiles and provides a summary for each port. * https://FreshPorts.org/[FreshPorts]: Provides the most up-to-date list of ports and port changes. Add your favourite ports to your watch list and receive email notification of any changes. -* https://portsmon.FreeBSD.org/[PortsMon]: Is a server which checks the Ports Collection and keeps package building logs and error logs for each port. [[storage]] == Storage * http://www.coda.cs.cmu.edu/[Coda]: A distributed filesystem. Among its features are disconnected operation, good security model, server replication and persistent client side caching. * http://www.ece.cmu.edu/~ganger/papers/[Journaling versus Soft Updates]: Asynchronous Meta-data Protection in File Systems. [[kernelandsecurity]] == Kernel, security * http://www.TrustedBSD.org/[TrustedBSD]: Provides a set of trusted operating system extensions to the FreeBSD operating system. This includes features such as fine-grained privileges (capabilities), Access Control Lists, and Mandatory Access Control. These features are being integrated back into the base FreeBSD distribution, as well as being ported to other BSD-derived systems. * https://people.freebsd.org/~pho/stress/index.html[Kernel Stress Test Suite]: The purpose of this stress test is to crash the system. The stress test is composed of small test programs and scripts. Each test targets a specific area of the kernel. The key concept of this test suite is chaos. Each test sleeps for a random number of seconds before it starts up in a random number of invocations. [[devicedrivers]] == Device drivers * https://people.FreeBSD.org/~fsmp/HomeAuto/HomeAuto.html[Home Automation]: Using FreeBSD to run appliance controllers, infra-red controllers, automated telephone systems, and more. [[architecture]] == Architecture * link:../platforms/ppc/[Porting FreeBSD to PowerPC(R) systems]: Contains information on the FreeBSD PPC port, such as mailing list information and so on. * http://www.cs.utah.edu/flux/oskit/[The OSKit]: The OSKit is a framework and a set of 31 component libraries oriented to operating systems, together with extensive documentation. By providing in a modular way not only most of the infrastructure "grunge" needed by an OS, but also many higher-level components, the OSKit's goal is to lower the barrier to entry to OS R&D and to lower its costs. The OSKit makes it vastly easier to create a new OS, port an existing OS to the x86 (or in the future, to other architectures supported by the OSkit), or enhance an OS to support a wider range of devices, filesystem formats, executable formats, or network services. The OSKit also works well for constructing OS-related programs, such as boot loaders or OS-level servers atop a microkernel. [[misc]] == Misc * link:{nanobsd}[NanoBSD]: NanoBSD is a tool designed to create a possibly reduced FreeBSD system image, which is suited to fit on a Compact Flash card (or other mass storage medium) in a way which is suitable for use in appliance like applications. The FreeBSD documentation collection includes an introductory link:{nanobsd}[article about NanoBSD], which includes useful tips about setting up, running and using NanoBSD. * http://www.gnu.org/software/global/global.html[GLOBAL]: A common source code tag system that works the same way across diverse environments. Currently, it supports the shell command line, the nvi editor, web browser, the emacs editor, and the elvis editor, and the supported languages are C, Yacc, and Java. * link:https://wiki.freebsd.org/ACPI[ACPI on FreeBSD]: A Project created to get ACPI working smoothly on FreeBSD. * http://wiki.freebsd.org/TestSuite[TestSuite]: This project aims to equip FreeBSD with a comprehensive test suite that is easy to run out of the box and during the development of the system. The goal of the test suite is to assist both developers and users in assessing the quality of FreeBSD.