Skip to content

Fix Issue 17649 - CONTRIBUTING.md instructions failed (no ../druntime… #1827

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 14, 2017
Merged

Fix Issue 17649 - CONTRIBUTING.md instructions failed (no ../druntime… #1827

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fb878c4
Add docs-release and docs-prerelease targets
wilzbach Jul 17, 2017
a557383
Fix Issue 17649 - CONTRIBUTING.md instructions failed (no ../druntime…
wilzbach Jul 17, 2017
ebf8e2c
Restructure & update CONTRIBUTING.md
wilzbach Jul 17, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 38 additions & 41 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,36 +11,34 @@ Make sure you have these prerequisites working:
* The C++ compiler for your platform (invokable as `gcc`)
* Optional: `latex` for building the pdf documentation
* Optional: `kindlegen` for building the Kindle documentation
* If you're running OSX, make sure you have some version of `libevent` installed
* If you're running OSX, make sure you have some version of `libevent` installed (needed for Ddox)

## Getting the code

Create a working directory for the D language, e.g. `~/code/d`. The remainder
of this document calls that directory henceforth `$R` from "Root". To get the
code:
If you already have a [working directory for the D language](https://wiki.dlang.org/Building_under_Posix#Fetch_repositories_from_GitHub),
e.g. `~/dlang`, change to it.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure that it is a good idea to suggest the same working directory as the one install.sh manages.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It use ~/dlang for a long time now and since we moved the checkouts into .generated, I haven't had any problems. Though it would have been nice for the install.sh script to support an alternate directory - see dlang/installer#274

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It use ~/dlang for a long time now

and I recall you said it caused problems due to conflicts between what the installer tool does and what the makefiles did.

I agree, we should change this, probably in the documentation.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for the typo: s/It/I/

and I recall you said it caused problems due to conflicts between what the installer tool does and what the makefiles did.

Yep, it used to. However, we fixed that with #1889

I agree, we should change this, probably in the documentation.

This was an outdated comment I saw by chance and accidentally never replied, so I thought it's a good idea to leave an answer here, but I don't see any need for action anymore.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, it used to. However, we fixed that with #1889

That's just one problem we know about.

This was an outdated comment I saw by chance and accidentally never replied, so I thought it's a good idea to leave an answer here, but I don't see any need for action anymore.

This is a minor issue, but otherwise I disagree. We have to places in the official material that refer to the same directory for different purposes. They don't conflict now, but it's still an unnecessary source of confusion and potential problems, for the same reason you don't use one variable for two different purposes.


To get the code, run:

```
cd $R
git clone https://github.com/dlang/dlang.org
git clone https://github.com/dlang/dmd
cd dlang.org
```

The `dmd` compiler is needed for processing the documentation.
The remainder of this document assumes that is your current working directory.

## Building the main site

Now in `$R` there are two directories called `dmd` and `dlang.org`. To
build the main site, run this:
To build the main site, run:

```
cd $R/dlang.org
make -f posix.mak html
```

This builds the `dmd` compiler itself first and then uses it to build the
website pages. You may see warnings while the compiler is built. After `make`
ended with error code 0, directory `$R/dlang.org/web` contains the produced HTML
files. Take a moment to open `$R/dlang.org/web/index.html` in a browser.
ended with error code 0, directory `web` contains the produced HTML
files. Take a moment to open `web/index.html` in a browser.

## Building the standard library documentation

Expand All @@ -54,48 +52,47 @@ currently being worked on. The "release" version is built with the "release"
compiler, and the current version is built with the current compiler (which we
already have from the previous step).

### Building the release libraries
### Building the `prerelease` libraries

Fortunately there's no need to fumble with version numbers and git tags etc.;
all is automated. Run this command:
The more interesting stuff to build is the prerelease libraries because in all
likelihood that's what needs looking at and testing.

```
cd $R/dlang.org
make -f posix.mak druntime-release
make -f posix.mak phobos-release
make -f posix.mak apidocs-release
make -f posix.mak docs-prerelease
```

These commands tell you the release being built in their first line of output.
Then they proceed and clone the appropriate release for `dmd`, `druntime`, and
`phobos`. After all commands have been executed, the following directories will
be present in `$R`: `dlang.org`, `dmd`, `dmd-2.083.2`, `druntime-2.083.2`, and
`phobos-2.083.2`. Note that the actual release number may not be `2.083.2`, but
should be the same for all three directories.
If you only want to build a specific part (e.g. Phobos), run:

The output is in `$R/dlang.org/web/phobos` and `$R/dlang.org/web/library`.
```
make -f posix.mak phobos-prerelease
```

### Building the prerelease libraries
(`docs-prerelease` is a shorthand for `dmd-prerelease`, `druntime-prerelease`, `phobos-releas` and `apidocs-prerelease`)

The more interesting stuff to build is the prerelease libraries because in all
likelihood that's what needs looking at and testing. To do that two more
repositories containing the core and standard libraries are needed: `druntime`
and `phobos`:
The output is in `web/phobos-prerelease` and `library-prerelease`.

### Building the `release` libraries

Fortunately there's no need to fumble with version numbers and git tags etc.;
all is automated. Run this command:

```
cd $R
git clone https://github.com/dlang/druntime
git clone https://github.com/dlang/phobos
make -f posix.mak docs-release
```

With the new repos in tow this builds the prerelease libraries:
If you only want to build a specific part (e.g. Phobos), run:

```
cd $R/dlang.org
make -f posix.mak druntime-prerelease
make -f posix.mak phobos-prerelease
make -f posix.mak apidocs-prerelease
make -f posix.mak phobos-release
```

The output is in `$R/dlang.org/web/phobos-prerelease` and
`$R/dlang.org/web/library-prerelease`.
(`docs-release` is a shorthand for `dmd-release`, `druntime-release`, `phobos-releas` and `apidocs-release`)

These commands tell you the release being built in their first line of output.
Then they proceed and clone the appropriate release for `dmd`, `druntime`, and
`phobos`. After all commands have been executed, the following directories will
be present in `$R`: `dlang.org`, `dmd`, `dmd-2.083.2`, `druntime-2.083.2`, and
`phobos-2.083.2`. Note that the actual release number may not be `2.083.2`, but
should be the same for all three directories.

The output is in `web/phobos` and `web/library`.
10 changes: 8 additions & 2 deletions posix.mak
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,10 @@ DMD_STABLE=$(DMD_STABLE_DIR)/generated/$(OS)/release/$(MODEL)/dmd
DRUNTIME_STABLE_DIR=${DRUNTIME_DIR}-${LATEST}
PHOBOS_STABLE_DIR=${PHOBOS_DIR}-${LATEST}

# Auto-cloning missing directories
$(shell [ ! -d $(DMD_DIR) ] && git clone --depth=1 ${GIT_HOME}/dmd $(DMD_DIR))
$(shell [ ! -d $(DRUNTIME_DIR) ] && git clone --depth=1 ${GIT_HOME}/druntime $(DRUNTIME_DIR))

################################################################################
# Automatically generated directories
GENERATED=.generated
Expand Down Expand Up @@ -230,8 +234,10 @@ ALL_FILES = $(ALL_FILES_BUT_SITEMAP) $(DOC_OUTPUT_DIR)/sitemap.html

all : docs html

docs : dmd-release dmd-prerelease phobos-prerelease druntime-prerelease \
druntime-release phobos-release apidocs-release apidocs-prerelease
docs-release: dmd-release druntime-release phobos-release apidocs-release
docs-prerelease: dmd-prerelease druntime-prerelease phobos-prerelease apidocs-prerelease

docs : docs-release docs-prerelease

html : $(ALL_FILES)

Expand Down